Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Fix docs list indentation from 3-space to 4-space for MkDocs rendering

Murtaza Nasir90bd4b2db32a
diff --git a/docs/admin-guide/retention.md b/docs/admin-guide/retention.md
index 62c3c05a..ddf7116c 100644
--- a/docs/admin-guide/retention.md
+++ b/docs/admin-guide/retention.md
@@ -294,37 +294,37 @@ This approach lets you keep years of searchable conversation history without acc
### For Compliance
1. **Set appropriate retention periods**
- ```bash
- # Example: 7-year retention for financial records
- GLOBAL_RETENTION_DAYS=2555 # 7 years × 365 days
- DELETION_MODE=full_recording
- ```
+ ```bash
+ # Example: 7-year retention for financial records
+ GLOBAL_RETENTION_DAYS=2555 # 7 years × 365 days
+ DELETION_MODE=full_recording
+ ```
2. **Use tag-based protection** for records requiring indefinite retention
- - Create "Legal Hold" or "Permanent" tags
- - Enable protection on these tags
- - Apply to relevant recordings
+ - Create "Legal Hold" or "Permanent" tags
+ - Enable protection on these tags
+ - Apply to relevant recordings
3. **Document your retention policy** in your organization's compliance documentation
### For Storage Management
1. **Start with audio-only deletion**
- ```bash
- DELETION_MODE=audio_only
- ```
- - Keeps searchable transcriptions
- - Frees up 95%+ of storage (audio files are large)
- - Maintains business value of conversations
+ ```bash
+ DELETION_MODE=audio_only
+ ```
+ - Keeps searchable transcriptions
+ - Frees up 95%+ of storage (audio files are large)
+ - Maintains business value of conversations
2. **Use shorter retention periods** for routine recordings
- ```bash
- GLOBAL_RETENTION_DAYS=30 # Routine meetings
- ```
+ ```bash
+ GLOBAL_RETENTION_DAYS=30 # Routine meetings
+ ```
3. **Protect important content** with tags
- - "Executive Meetings" tag → protect from deletion
- - "Daily Standup" tag → no protection (routine)
+ - "Executive Meetings" tag → protect from deletion
+ - "Daily Standup" tag → no protection (routine)
### For Groups
@@ -366,21 +366,21 @@ Example group tag retention configuration:
### Enabling Auto-Deletion on Existing System
1. **Test with audio-only mode first:**
- ```bash
- ENABLE_AUTO_DELETION=true
- GLOBAL_RETENTION_DAYS=365 # Start with long period
- DELETION_MODE=audio_only # Test safely
- ```
+ ```bash
+ ENABLE_AUTO_DELETION=true
+ GLOBAL_RETENTION_DAYS=365 # Start with long period
+ DELETION_MODE=audio_only # Test safely
+ ```
2. **Protect existing important content:**
- - Create protected tags
- - Apply to critical recordings
- - Verify exemptions via `/admin/auto-deletion/stats`
+ - Create protected tags
+ - Apply to critical recordings
+ - Verify exemptions via `/admin/auto-deletion/stats`
3. **Run manual test:**
- ```bash
- POST /admin/auto-deletion/run
- ```
+ ```bash
+ POST /admin/auto-deletion/run
+ ```
4. **Monitor results** and adjust retention period as needed
diff --git a/docs/admin-guide/sso-setup.md b/docs/admin-guide/sso-setup.md
index 5d006638..d213fe49 100644
--- a/docs/admin-guide/sso-setup.md
+++ b/docs/admin-guide/sso-setup.md
@@ -43,13 +43,13 @@ Restart Speakr after updating environment variables.
## Keycloak quick start
1. In Keycloak, create a new client (e.g., `speakr`) with:
- - **Client Type**: OpenID Connect
- - **Access Type**: Confidential
- - **Valid Redirect URI**: `https://your-host/auth/sso/callback`
- - **Web Origins**: `+` (or your domain)
+ - **Client Type**: OpenID Connect
+ - **Access Type**: Confidential
+ - **Valid Redirect URI**: `https://your-host/auth/sso/callback`
+ - **Web Origins**: `+` (or your domain)
2. Copy the **Client ID** and **Client Secret**.
3. Note the **OpenID Endpoint Configuration** (discovery) URL, typically:
- `https://<host>/realms/<realm>/.well-known/openid-configuration`
+ `https://<host>/realms/<realm>/.well-known/openid-configuration`
4. Set the environment variables accordingly and restart Speakr.
@@ -60,7 +60,7 @@ Restart Speakr after updating environment variables.
3. Grant API permissions: `openid`, `profile`, `email`.
4. Create a client secret.
5. Discovery URL format:
- `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
+ `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
6. Set variables and restart.
@@ -69,7 +69,7 @@ Restart Speakr after updating environment variables.
1. Create OAuth credentials (Web application).
2. Add authorized redirect URI: `https://your-host/auth/sso/callback`.
3. Use discovery URL:
- `https://accounts.google.com/.well-known/openid-configuration`
+ `https://accounts.google.com/.well-known/openid-configuration`
4. Set variables and restart.
@@ -78,7 +78,7 @@ Restart Speakr after updating environment variables.
1. Create a Regular Web Application.
2. Allowed Callback URLs: `https://your-host/auth/sso/callback`.
3. Discovery URL:
- `https://<your-tenant>.auth0.com/.well-known/openid-configuration`
+ `https://<your-tenant>.auth0.com/.well-known/openid-configuration`
4. Set variables and restart.
diff --git a/docs/admin-guide/whisperx-setup.md b/docs/admin-guide/whisperx-setup.md
index 4d7e0b09..54996321 100644
--- a/docs/admin-guide/whisperx-setup.md
+++ b/docs/admin-guide/whisperx-setup.md
@@ -73,13 +73,13 @@ cd whisperx-asr-service
You must accept agreements for **all three models** used by the diarization pipeline:
1. **Main diarization model:**
- - [https://huggingface.co/pyannote/speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1)
+ - [https://huggingface.co/pyannote/speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1)
2. **Segmentation model:**
- - [https://huggingface.co/pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
+ - [https://huggingface.co/pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
3. **Speaker diarization 3.1:**
- - [https://huggingface.co/pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
+ - [https://huggingface.co/pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
For each model:
@@ -176,15 +176,15 @@ If WhisperX is on a dedicated GPU server:
**On GPU Machine:**
1. Expose service to network in `docker-compose.yml`:
- ```yaml
- ports:
+ ```yaml
+ ports:
- "0.0.0.0:9000:9000"
- ```
+ ```
2. Configure firewall:
- ```bash
- sudo ufw allow 9000/tcp
- ```
+ ```bash
+ sudo ufw allow 9000/tcp
+ ```
**On Speakr Machine:**
diff --git a/docs/ci-cd-setup.md b/docs/ci-cd-setup.md
index cd54d147..4fe134fc 100644
--- a/docs/ci-cd-setup.md
+++ b/docs/ci-cd-setup.md
@@ -11,13 +11,13 @@ The Speakr project uses GitHub Actions to automatically build and publish Docker
1. When code is pushed to the `master` branch or a new tag is created (in the format `v*.*.*`), the GitHub Actions workflow is triggered.
2. The workflow builds a Docker image using the project's Dockerfile.
3. If the trigger was a push to the `master` branch, the image is tagged with:
- - `latest`
- - The short SHA of the commit
- - The branch name (`master`)
+ - `latest`
+ - The short SHA of the commit
+ - The branch name (`master`)
4. If the trigger was a new tag (e.g., `v1.2.3`), the image is tagged with:
- - The full version (`1.2.3`)
- - The major.minor version (`1.2`)
- - The tag name (`v1.2.3`)
+ - The full version (`1.2.3`)
+ - The major.minor version (`1.2`)
+ - The tag name (`v1.2.3`)
5. The image is then pushed to Docker Hub under your account.
### Setup Instructions
@@ -25,33 +25,33 @@ The Speakr project uses GitHub Actions to automatically build and publish Docker
To set up automatic Docker image publishing, follow these steps:
1. **Create a Docker Hub Account** (if you don't already have one):
- - Go to [Docker Hub](https://hub.docker.com/) and sign up for an account.
- - Create a repository named `speakr`.
+ - Go to [Docker Hub](https://hub.docker.com/) and sign up for an account.
+ - Create a repository named `speakr`.
2. **Create a Docker Hub Access Token**:
- - Log in to Docker Hub.
- - Go to your account settings by clicking on your username in the top-right corner and selecting "Account Settings".
- - Navigate to the "Security" tab.
- - Click "New Access Token".
- - Give your token a name (e.g., "GitHub Actions") and set the appropriate permissions (at least "Read & Write").
- - Copy the generated token (you won't be able to see it again).
+ - Log in to Docker Hub.
+ - Go to your account settings by clicking on your username in the top-right corner and selecting "Account Settings".
+ - Navigate to the "Security" tab.
+ - Click "New Access Token".
+ - Give your token a name (e.g., "GitHub Actions") and set the appropriate permissions (at least "Read & Write").
+ - Copy the generated token (you won't be able to see it again).
3. **Add Docker Hub Credentials to GitHub Secrets**:
- - Go to your GitHub repository.
- - Click on "Settings" > "Secrets and variables" > "Actions".
- - Click "New repository secret".
- - Add the following secrets:
+ - Go to your GitHub repository.
+ - Click on "Settings" > "Secrets and variables" > "Actions".
+ - Click "New repository secret".
+ - Add the following secrets:
- Name: `DOCKERHUB_USERNAME`, Value: Your Docker Hub username
- Name: `DOCKERHUB_TOKEN`, Value: The access token you generated in the previous step
4. **Verify the Workflow**:
- - The workflow file is located at `.github/workflows/docker-publish.yml`.
- - It's already configured to build and push Docker images to Docker Hub.
- - You can customize it further if needed.
+ - The workflow file is located at `.github/workflows/docker-publish.yml`.
+ - It's already configured to build and push Docker images to Docker Hub.
+ - You can customize it further if needed.
5. **Trigger the Workflow**:
- - Push a change to the `master` branch or create a new tag to trigger the workflow.
- - Go to the "Actions" tab in your GitHub repository to monitor the workflow's progress.
+ - Push a change to the `master` branch or create a new tag to trigger the workflow.
+ - Go to the "Actions" tab in your GitHub repository to monitor the workflow's progress.
### Using the Published Docker Images
@@ -80,10 +80,10 @@ To create a new version of your application:
1. Make your changes and commit them to the repository.
2. Create a new tag following semantic versioning:
- ```bash
- git tag v1.0.0 # Replace with the appropriate version number
- git push origin v1.0.0
- ```
+ ```bash
+ git tag v1.0.0 # Replace with the appropriate version number
+ git push origin v1.0.0
+ ```
3. The GitHub Actions workflow will automatically build and publish a new Docker image with the appropriate version tags.
This allows users to choose between using the latest version (`learnedmachine/speakr:latest`) or a specific version (`learnedmachine/speakr:1.0.0`).
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a8a277b0..fdf92e4e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -151,11 +151,11 @@ Group tags automatically share recordings with all group members when applied:
1. While editing or creating a group, navigate to the **Tags** section
2. Click "Create Group Tag" and enter:
- - **Tag Name**: What the tag will be called (e.g., "Team Meetings", "Family Events")
- - **Color**: Choose a color for easy visual identification
- - **Custom Prompt** (optional): AI instructions for how to summarize recordings with this tag
- - **Protected**: Enable to prevent automatic deletion by retention policies
- - **Retention Days** (optional): Auto-delete recordings after this many days (leave blank to keep forever)
+ - **Tag Name**: What the tag will be called (e.g., "Team Meetings", "Family Events")
+ - **Color**: Choose a color for easy visual identification
+ - **Custom Prompt** (optional): AI instructions for how to summarize recordings with this tag
+ - **Protected**: Enable to prevent automatic deletion by retention policies
+ - **Retention Days** (optional): Auto-delete recordings after this many days (leave blank to keep forever)
3. Save the tag
When any group member applies this tag to a recording, all group members automatically get access to it.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index ba35c78d..f0885d25 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -139,23 +139,23 @@ For the best transcription and diarization quality, self-hosting an ASR service
**ASR Service Options:**
1. **WhisperX ASR Service (Recommended)** - Best transcription quality with voice profile support
- - Repository: [murtaza-nasir/whisperx-asr-service](https://github.com/murtaza-nasir/whisperx-asr-service)
- - Uses `pyannote/speaker-diarization-community-1` model with exclusive diarization
- - **Superior transcription and diarization quality** with large models (large-v3, distil-large-v3)
- - Supports 256-dimensional speaker embeddings for voice profile identification
- - Better timestamp alignment between speakers and words
- - **Required for:** Voice profiles, automatic speaker recognition, speaker embeddings
- - **Environment file:** `config/env.whisperx.example`
- - **Required setting:** `ASR_RETURN_SPEAKER_EMBEDDINGS=true` to enable voice profile features
+ - Repository: [murtaza-nasir/whisperx-asr-service](https://github.com/murtaza-nasir/whisperx-asr-service)
+ - Uses `pyannote/speaker-diarization-community-1` model with exclusive diarization
+ - **Superior transcription and diarization quality** with large models (large-v3, distil-large-v3)
+ - Supports 256-dimensional speaker embeddings for voice profile identification
+ - Better timestamp alignment between speakers and words
+ - **Required for:** Voice profiles, automatic speaker recognition, speaker embeddings
+ - **Environment file:** `config/env.whisperx.example`
+ - **Required setting:** `ASR_RETURN_SPEAKER_EMBEDDINGS=true` to enable voice profile features
2. **OpenAI Whisper ASR Webservice** - For basic speaker diarization without voice profiles
- - Repository: [ahmetoner/whisper-asr-webservice](https://github.com/ahmetoner/whisper-asr-webservice)
- - Uses `pyannote/speaker-diarization-3.1` model
- - Simpler setup, less resource intensive
- - **Supports:** Basic speaker identification (Speaker 1, Speaker 2, etc.)
- - **Does not support:** Voice profiles, speaker embeddings, automatic speaker recognition
- - **Environment file:** `config/env.asr.example`
- - **Note:** Do not set `ASR_RETURN_SPEAKER_EMBEDDINGS=true` with this service as it will cause errors
+ - Repository: [ahmetoner/whisper-asr-webservice](https://github.com/ahmetoner/whisper-asr-webservice)
+ - Uses `pyannote/speaker-diarization-3.1` model
+ - Simpler setup, less resource intensive
+ - **Supports:** Basic speaker identification (Speaker 1, Speaker 2, etc.)
+ - **Does not support:** Voice profiles, speaker embeddings, automatic speaker recognition
+ - **Environment file:** `config/env.asr.example`
+ - **Note:** Do not set `ASR_RETURN_SPEAKER_EMBEDDINGS=true` with this service as it will cause errors
> **Important:** Before proceeding with this configuration, you'll need to set up one of the ASR service containers. See [Running ASR Service for Speaker Diarization](#running-asr-service-for-speaker-diarization) for complete instructions on deploying both containers together or separately.
@@ -451,9 +451,9 @@ If you need speaker diarization to identify different speakers in your recording
**Prerequisites:**
1. **Hugging Face Account & Model Access** - Visit and accept terms for ALL models:
- - [pyannote/speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1)
- - [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
- - [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
+ - [pyannote/speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1)
+ - [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
+ - [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
2. **Generate HF Token** - Create a read-access token at [Hugging Face Settings](https://huggingface.co/settings/tokens)
@@ -495,8 +495,8 @@ See the [WhisperX ASR Service README](https://github.com/murtaza-nasir/whisperx-
**Prerequisites:**
1. **Hugging Face Account & Model Access** - Visit and accept terms:
- - [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
- - [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
+ - [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
+ - [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
2. **Generate HF Token** - Create a read-access token at [Hugging Face Settings](https://huggingface.co/settings/tokens)
diff --git a/docs/user-guide/api-tokens.md b/docs/user-guide/api-tokens.md
index d27f7b45..c1b4bf48 100644
--- a/docs/user-guide/api-tokens.md
+++ b/docs/user-guide/api-tokens.md
@@ -20,8 +20,8 @@ API tokens are personal access tokens that authenticate API requests on your beh
2. Click **Create Token**
3. Enter a descriptive name (e.g., "n8n automation", "CLI access")
4. Choose an expiration period:
- - **No expiration** - Token remains valid until manually revoked
- - **30 days**, **90 days**, **1 year** - Token automatically expires
+ - **No expiration** - Token remains valid until manually revoked
+ - **30 days**, **90 days**, **1 year** - Token automatically expires
5. Click **Create**
!!! important "Save Your Token"
diff --git a/docs/user-guide/first-steps.md b/docs/user-guide/first-steps.md
index 75368cab..9b18f877 100644
--- a/docs/user-guide/first-steps.md
+++ b/docs/user-guide/first-steps.md
@@ -138,9 +138,9 @@ For one-off collaborations or sharing with specific people outside your groups:
2. Click the **share icon** (users icon) in the toolbar
3. Search for the user's name and select them
4. Choose their permission level:
- - **View Only**: Can read and listen, but not edit
- - **Edit**: Can modify metadata, notes, and summary
- - **Reshare**: Can share with additional users
+ - **View Only**: Can read and listen, but not edit
+ - **Edit**: Can modify metadata, notes, and summary
+ - **Reshare**: Can share with additional users
5. Click to add them - they immediately receive access
### Personal Notes on Shared Recordings
diff --git a/docs/user-guide/pwa.md b/docs/user-guide/pwa.md
index 11313063..c622495d 100644
--- a/docs/user-guide/pwa.md
+++ b/docs/user-guide/pwa.md
@@ -20,9 +20,9 @@ A Progressive Web App combines the best of web and mobile apps:
2. Look for the **"Add to Home Screen"** prompt at the bottom of the screen
3. Tap **"Add"** or **"Install"**
4. Alternatively:
- - Tap the three-dot menu (⋮) in the browser
- - Select **"Add to Home screen"** or **"Install app"**
- - Follow the prompts
+ - Tap the three-dot menu (⋮) in the browser
+ - Select **"Add to Home screen"** or **"Install app"**
+ - Follow the prompts
5. **Launch** the app from your home screen
@@ -49,8 +49,8 @@ A Progressive Web App combines the best of web and mobile apps:
2. Look for the **install icon** (⊕) in the address bar
3. Click it and select **"Install"**
4. Alternatively:
- - Click the three-dot menu
- - Select **"Install Speakr"** or **"Add to applications"**
+ - Click the three-dot menu
+ - Select **"Install Speakr"** or **"Add to applications"**
5. **Launch** from your applications menu or desktop shortcut
diff --git a/docs/user-guide/transcript-templates.md b/docs/user-guide/transcript-templates.md
index 3f551e8a..62f68c66 100644
--- a/docs/user-guide/transcript-templates.md
+++ b/docs/user-guide/transcript-templates.md
@@ -291,30 +291,30 @@ Groups using wikis or documentation platforms can create templates that match th
Here's a complete setup for automatic export to Obsidian:
1. **Enable auto-export in `.env`**:
- ```bash
- ENABLE_AUTO_EXPORT=true
- AUTO_EXPORT_DIR=/data/exports
- AUTO_EXPORT_TRANSCRIPTION=true
- AUTO_EXPORT_SUMMARY=true
- ```
+ ```bash
+ ENABLE_AUTO_EXPORT=true
+ AUTO_EXPORT_DIR=/data/exports
+ AUTO_EXPORT_TRANSCRIPTION=true
+ AUTO_EXPORT_SUMMARY=true
+ ```
2. **Map exports to Obsidian vault in `docker-compose.yml`**:
- ```yaml
- volumes:
+ ```yaml
+ volumes:
- ./uploads:/data/uploads
- ./instance:/data/instance
- /Users/username/Documents/Obsidian/Transcripts:/data/exports
- ```
+ ```
3. **Create a default transcript template** in Speakr settings with the format you want:
- ```
- [{{start_time}}] {{speaker}}: {{text}}
- ```
+ ```
+ [{{start_time}}] {{speaker}}: {{text}}
+ ```
4. **Restart Speakr** to apply the changes:
- ```bash
- docker compose restart
- ```
+ ```bash
+ docker compose restart
+ ```
Now when any recording finishes processing, Speakr automatically writes a markdown file to your Obsidian vault with: