Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
doc improvements
Murtaza Nasircc9ffbe8d626
diff --git a/README.md b/README.mdindex cb81ca48..c0f4e754 100644--- a/README.md+++ b/README.md@@ -48,12 +48,17 @@ Speakr transforms your audio recordings into organized, searchable, and intellig# Create project directorymkdir speakr && cd speakr-# Download configuration+# Download configuration (choose one):wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/docker-compose.example.yml -O docker-compose.yml++# For OpenAI or similar Whisper API:wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env-# Configure your API keys-nano .env # Add your OpenAI/OpenRouter API keys+# OR for ASR with speaker diarization (requires additional container):+wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env++# Configure your service endpoints and API keys+nano .env # Set API endpoints (Local/OpenAI/OpenRouter/etc) and add your API keys# Launch Speakrdocker compose up -d@@ -61,6 +66,8 @@ docker compose up -d# Access at http://localhost:8899```+**Note:** ASR option requires running `onerahmet/openai-whisper-asr-webservice` container alongside Speakr. See [installation guide](https://murtaza-nasir.github.io/speakr/getting-started/installation#running-asr-service-for-speaker-diarization) for complete setup.+**[View Full Installation Guide →](https://murtaza-nasir.github.io/speakr/getting-started)**## Documentationdiff --git a/docs/assets/images/screenshots/Filters.png b/docs/assets/images/screenshots/Filters.pngindex 5b0774ad..cc5fa2c8 100644Binary files a/docs/assets/images/screenshots/Filters.png and b/docs/assets/images/screenshots/Filters.png differdiff --git a/docs/getting-started.md b/docs/getting-started.mdindex 624894df..92e83c60 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -2,6 +2,8 @@Get Speakr up and running in just a few minutes using the pre-built Docker image! This guide will walk you through the fastest way to deploy Speakr with either OpenAI Whisper API or a [custom ASR endpoint](features.md#speaker-diarization).+> **Note:** If you want to use the ASR endpoint option for speaker diarization features, you'll need to run an additional Docker container (`onerahmet/openai-whisper-asr-webservice`). See [Running ASR Service for Speaker Diarization](getting-started/installation.md#running-asr-service-for-speaker-diarization) for detailed setup instructions.+## PrerequisitesBefore you begin, make sure you have Docker and Docker Compose installed on your system. You'll also need an API key for either OpenAI or OpenRouter (or a compatible service), at least 2GB of available RAM, and about 10GB of available disk space for storing recordings and transcriptions.@@ -31,11 +33,13 @@ For standard OpenAI Whisper API (recommended for most users):wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env```-Or for a custom ASR endpoint with speaker diarization:+Or for a custom ASR endpoint with speaker diarization (requires additional ASR container - see note below):```bashwget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env```+> **Important:** The ASR endpoint option requires running an additional Docker container (`onerahmet/openai-whisper-asr-webservice`) alongside Speakr. For complete setup instructions including docker-compose configurations for both containers, see [Running ASR Service for Speaker Diarization](getting-started/installation.md#running-asr-service-for-speaker-diarization).+## Step 3: Configure Your Transcription ServiceOpen the `.env` file in your preferred text editor and configure it based on your chosen service.@@ -62,6 +66,11 @@ The text model can use OpenRouter for access to various AI models, or you can po### Option B: Custom ASR Endpoint Configuration+> **Prerequisites:** This option requires running an additional ASR service container (`onerahmet/openai-whisper-asr-webservice`). You can either:+> - Run both containers in the same Docker Compose stack (recommended) - see [complete setup guide](getting-started/installation.md#running-asr-service-for-speaker-diarization)+> - Run the ASR service separately on the same or different machine+> - Use an existing ASR service if you already have one deployed+If you're using a custom ASR service like WhisperX or a self-hosted Whisper server, configure these variables:```bashdiff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.mdindex d4320f54..fa537ab0 100644--- a/docs/getting-started/installation.md+++ b/docs/getting-started/installation.md@@ -6,7 +6,7 @@ This comprehensive guide covers deploying Speakr for production use, including dBefore diving into installation, it's helpful to understand how Speakr works. The application integrates with external APIs for two main purposes: transcription services that convert your audio to text, and text generation services that power features like summaries, titles, and interactive chat. Speakr is designed to be flexible, supporting both cloud-based services like OpenAI and self-hosted solutions running on your own infrastructure.-Speakr uses specific API endpoint formats for these integrations. For transcription, it supports the standard OpenAI Whisper API format using the `/audio/transcriptions` endpoint, which is implemented by OpenAI, OpenRouter, and many self-hosted solutions. Alternatively, for advanced features like speaker diarization, Speakr can connect to ASR webservices that provide an `/asr` endpoint. For text generation, Speakr uses the OpenAI Chat Completions API format with the `/chat/completions` endpoint, which is widely supported across different AI providers.+Speakr uses specific API endpoint formats for these integrations. For transcription, it supports the standard OpenAI Whisper API format using the `/audio/transcriptions` endpoint, which is implemented by OpenAI, OpenRouter, and many self-hosted solutions. Alternatively, for advanced features like speaker diarization, Speakr can connect to ASR webservices that provide an `/asr` endpoint. **Note: Using the ASR endpoint option requires running an additional Docker container** (`onerahmet/openai-whisper-asr-webservice`) alongside Speakr - full setup instructions are provided in the [Running ASR Service for Speaker Diarization](#running-asr-service-for-speaker-diarization) section below. For text generation, Speakr uses the OpenAI Chat Completions API format with the `/chat/completions` endpoint, which is widely supported across different AI providers.## Prerequisites@@ -88,7 +88,11 @@ WHISPER_MODEL=whisper-1#### For Custom ASR Endpoint with Speaker Diarization-If you want speaker diarization to identify who's speaking in your recordings, you'll need to use an ASR webservice endpoint. This requires running a separate service, but provides powerful features for meeting transcriptions and multi-speaker recordings:+If you want speaker diarization to identify who's speaking in your recordings, you'll need to use an ASR webservice endpoint. **This requires running an additional Docker container** (`onerahmet/openai-whisper-asr-webservice`) alongside Speakr, but provides powerful features for meeting transcriptions and multi-speaker recordings.++> **Important:** Before proceeding with this configuration, you'll need to set up the ASR service container. See [Running ASR Service for Speaker Diarization](#running-asr-service-for-speaker-diarization) for complete instructions on deploying both containers together or separately.++Download the ASR configuration template:```bashwget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env@@ -218,7 +222,7 @@ If transcription fails, check the Docker logs for API authentication errors or c### Running ASR Service for Speaker Diarization-If you need speaker diarization to identify different speakers in your recordings, you'll need to run an ASR service alongside Speakr. The recommended approach is using the WhisperX-based ASR webservice in the same Docker Compose stack.+If you need speaker diarization to identify different speakers in your recordings, you'll need to run an ASR service alongside Speakr. This involves deploying an additional Docker container (`onerahmet/openai-whisper-asr-webservice`) that provides the ASR endpoint. The recommended approach is running both containers in the same Docker Compose stack for simplified networking and management.First, you'll need a Hugging Face token to access the speaker diarization models. Create an account at Hugging Face, generate an access token, and importantly, visit the model pages for pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 to accept their terms. These are gated models that require explicit approval.@@ -270,6 +274,144 @@ networks:When running both services in the same Docker Compose file, containers communicate using service names. In your `.env` file, set `ASR_BASE_URL=http://whisper-asr:9000` using the service name, not localhost or an IP address. This is a common source of confusion but is how Docker networking works.+#### Running Services in Separate Docker Compose Files++If you prefer to manage the services independently or are adding the ASR service to an existing Speakr installation, you can run them in separate Docker Compose files. This approach gives you more flexibility and works whether the services are on the same machine or different machines.++##### Option 1: Same Machine with Shared Network++If both services run on the same machine, you can use Docker's internal networking for communication:++First, create a shared Docker network:++```bash+docker network create speakr-network+```++Create `docker-compose.asr.yml` for the ASR service:++```yaml+services:+ whisper-asr:+ image: onerahmet/openai-whisper-asr-webservice:latest-gpu+ container_name: whisper-asr-webservice+ ports:+ - "9000:9000"+ environment:+ - ASR_MODEL=distil-large-v3+ - ASR_COMPUTE_TYPE=int8+ - ASR_ENGINE=whisperx+ - HF_TOKEN=your_huggingface_token_here+ deploy:+ resources:+ reservations:+ devices:+ - driver: nvidia+ capabilities: [gpu]+ device_ids: ["0"]+ restart: unless-stopped+ networks:+ - speakr-network++networks:+ speakr-network:+ external: true+```++Update your Speakr `docker-compose.yml` to use the shared network:++```yaml+services:+ app:+ image: learnedmachine/speakr:latest+ container_name: speakr+ restart: unless-stopped+ ports:+ - "8899:8899"+ env_file:+ - .env+ volumes:+ - ./uploads:/data/uploads+ - ./instance:/data/instance+ networks:+ - speakr-network++networks:+ speakr-network:+ external: true+```++In your `.env` file, use the container name:+```bash+ASR_BASE_URL=http://whisper-asr-webservice:9000+```++##### Option 2: Separate Machines++When running on different machines, you don't need the shared network. Each service runs independently and communicates over the network using IP addresses or hostnames.++On the ASR server, create `docker-compose.asr.yml`:++```yaml+services:+ whisper-asr:+ image: onerahmet/openai-whisper-asr-webservice:latest-gpu+ container_name: whisper-asr-webservice+ ports:+ - "9000:9000" # Exposed to the network+ environment:+ - ASR_MODEL=distil-large-v3+ - ASR_COMPUTE_TYPE=int8+ - ASR_ENGINE=whisperx+ - HF_TOKEN=your_huggingface_token_here+ deploy:+ resources:+ reservations:+ devices:+ - driver: nvidia+ capabilities: [gpu]+ device_ids: ["0"]+ restart: unless-stopped+```++On the Speakr server, use the standard `docker-compose.yml`:++```yaml+services:+ app:+ image: learnedmachine/speakr:latest+ container_name: speakr+ restart: unless-stopped+ ports:+ - "8899:8899"+ env_file:+ - .env+ volumes:+ - ./uploads:/data/uploads+ - ./instance:/data/instance+```++In your Speakr `.env` file, use the ASR server's IP address or hostname:+```bash+# Using IP address+ASR_BASE_URL=http://192.168.1.100:9000++# Or using hostname+ASR_BASE_URL=http://asr-server.local:9000+```++Start both services on their respective machines:++```bash+# On ASR server+docker compose -f docker-compose.asr.yml up -d++# On Speakr server+docker compose up -d+```++Make sure port 9000 is accessible between the machines (check firewall rules if needed).+## Production Considerations### Using a Reverse Proxy for SSLdiff --git a/docs/github-secrets-guide.md b/docs/github-secrets-guide.mddeleted file mode 100644index 09291eff..00000000--- a/docs/github-secrets-guide.md+++ /dev/null@@ -1,64 +0,0 @@-# Adding GitHub Secrets for Docker Hub Authentication--This guide provides step-by-step instructions on how to add your Docker Hub credentials as secrets in your GitHub repository.--## Step 1: Generate a Docker Hub Access Token--1. Log in to your Docker Hub account at [https://hub.docker.com/](https://hub.docker.com/)-2. Click on your username in the top-right corner and select "Account Settings"-3. In the left sidebar, click on "Security"-4. Click the "New Access Token" button-5. Give your token a descriptive name (e.g., "GitHub Actions")-6. Select "Read & Write" permissions-7. Click "Generate"-8. **IMPORTANT**: Copy the generated token immediately and save it somewhere secure. You won't be able to see it again after you leave this page.--## Step 2: Add Secrets to Your GitHub Repository--1. Go to your GitHub repository at [https://github.com/murtaza-nasir/speakr](https://github.com/murtaza-nasir/speakr)-2. Click on the "Settings" tab near the top of the page-3. In the left sidebar, click on "Secrets and variables", then select "Actions"-4. Click the "New repository secret" button-5. Add your Docker Hub username:- - Name: `DOCKERHUB_USERNAME`- - Value: Your Docker Hub username- - Click "Add secret"-6. Click the "New repository secret" button again-7. Add your Docker Hub access token:- - Name: `DOCKERHUB_TOKEN`- - Value: The access token you generated in Step 1- - Click "Add secret"--## Step 3: Verify the Secrets--1. After adding both secrets, they should appear in the "Repository secrets" list-2. The actual values will be hidden for security reasons-3. These secrets are now available for use in your GitHub Actions workflows--## Step 4: Test the Workflow--1. Make a small change to your repository and push it to the `master` branch-2. Go to the "Actions" tab in your GitHub repository-3. You should see the "Docker Build and Publish" workflow running-4. Once completed successfully, check your Docker Hub repository to verify that the image was pushed--## Troubleshooting--If the workflow fails with authentication errors:-- Verify that the secrets are named exactly `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`-- Check that your Docker Hub access token has "Read & Write" permissions-- Ensure that your Docker Hub account has a repository with the same name as your GitHub repository (`speakr`)-- Check the workflow logs for specific error messages--## Screenshots--Here's a visual guide to help you navigate the GitHub interface:--### Finding the Settings Tab---### Navigating to Secrets and Variables---### Adding a New Secret-diff --git a/mkdocs.yml b/mkdocs.ymlindex a7238d98..a175e00a 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -147,7 +147,6 @@ exclude_docs: |README.mdDOCUMENTATION_VERIFICATION_CHECKLIST.mdci-cd-setup.md- github-secrets-guide.md.github-deploy.ymlnav: