Skip to content

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

Python

updated readme

Murtaza Nasir017a39dc8a6d
diff --git a/README.md b/README.md
index 4ae374e2..8a24fc9c 100644
--- a/README.md
+++ b/README.md
@@ -306,125 +306,10 @@ Follow these steps if you want to modify the code or build the Docker image your
<details>
<summary><strong>Advanced Configuration & Technical Details</strong></summary>
-## API Endpoint Requirements
-
-Speakr integrates with external APIs for transcription and text generation. Here are the exact endpoints each service must implement:
-
-### Transcription Services
-
-**Standard Whisper API Method:**
-- **Endpoint:** `/audio/transcriptions`
-- **Method:** POST
-- **Format:** OpenAI Whisper API compatible
-- **Used for:** Audio transcription
-- **When:** When `USE_ASR_ENDPOINT=false` (default)
-
-**_Common providers using this method:_**
-- **OpenAI Whisper API** (`https://api.openai.com/v1`) - The original OpenAI service
-- **OpenRouter** (`https://openrouter.ai/api/v1`) - Multi-provider API gateway
-- **Local APIs** (`http://localhost:1234/v1`) - Self-hosted solutions like LM Studio, Ollama, or custom deployments
-- **Other API providers** - Any service implementing the OpenAI Whisper API format
-
-**ASR Webservice Method:**
-- **Endpoint:** `/asr`
-- **Method:** POST
-- **Format:** Custom ASR webservice format
-- **Used for:** Audio transcription with speaker diarization support
-- **When:** When `USE_ASR_ENDPOINT=true`
-
-**_Recommended provider:_**
-- **onerahmet/openai-whisper-asr-webservice** - Docker image that provides the `/asr` endpoint with WhisperX engine support for speaker diarization
-
-### Text Generation Services
-
-**Chat Completions API:**
-- **Endpoint:** `/chat/completions`
-- **Method:** POST
-- **Format:** OpenAI Chat Completions API compatible
-- **Used for:**
- - AI-generated titles and summaries
- - Interactive chat with transcriptions
- - Automatic speaker identification
- - Summary reprocessing
-- **When:** Always (for all text generation features)
-
-**_Common providers using this method:_**
-- **OpenAI** (`https://api.openai.com/v1`) - GPT models
-- **OpenRouter** (`https://openrouter.ai/api/v1`) - Access to multiple LLM providers
-- **Local APIs** (`http://localhost:1234/v1`) - Self-hosted solutions like LM Studio, Ollama, vLLM, or custom deployments
-- **Other API providers** - Anthropic, Google, Azure OpenAI, or any service implementing the OpenAI Chat Completions format
-
-**_Example API Base URLs:_**
-- OpenAI: `https://api.openai.com/v1`
-- OpenRouter: `https://openrouter.ai/api/v1`
-- Local APIs: `http://localhost:1234/v1`
-
-## Setup Instructions
-
-**For detailed deployment instructions, see the [Deployment Guide](DEPLOYMENT_GUIDE.md)**
+**For detailed deployment instructions and information about the various API's used, see the [Deployment Guide](DEPLOYMENT_GUIDE.md#configuration-options)**
The recommended method is to use the pre-built Docker image, which is fast and simple. This is explained above.
-### Advanced Setup (Build from Source)
-
-If you want to modify the code or build the Docker image yourself, clone the repository first.
-
-1. **Clone the Repository:**
- ```bash
- git clone https://github.com/murtaza-nasir/speakr.git
- cd speakr
- ```
-2. **Create `docker-compose.yml` and `.env` files:**
- Copy the example files from the repository.
- ```bash
- cp docker-compose.example.yml docker-compose.yml
-
- # For standard API
- cp env.whisper.example .env
-
- # OR for ASR Webservice
- cp env.asr.example .env
- ```
- Edit the `.env` file with your settings.
-3. **Build and Start:**
- ```bash
- docker compose up -d --build
- ```
-
-### Recommended ASR Webservice Setup
-
-**Speaker Diarization only works with the ASR method and requires the `whisperx` engine.** Here is an example `docker-compose.yml` for running the ASR service itself. You would run this *in addition* to the Speakr app container.
-
-```yaml
-services:
- whisper-asr-webservice:
- image: onerahmet/openai-whisper-asr-webservice:latest-gpu
- container_name: whisper-asr-webservice
- ports:
- - "9000:9000"
- environment:
- - ASR_MODEL=distil-large-v3 # or large-v3, medium
- - ASR_COMPUTE_TYPE=float16 # or int8, float32
- - ASR_ENGINE=whisperx # REQUIRED for diarization
- - HF_TOKEN=your_hugging_face_token # Optional
- deploy:
- resources:
- reservations:
- devices:
- - driver: nvidia
- capabilities: [gpu]
- device_ids: ["0"]
- restart: unless-stopped
-```
-
-**A Note on Diarization Accuracy:** For best results, it is often better to set the number of speakers slightly higher (e.g., by 1-2) than the actual number present. You can easily merge speakers later in the speaker identification modal.
-
-Speakr has been tested with the recommended `onerahmet/openai-whisper-asr-webservice` image. Other ASR webservices might work but have not been tested.
-
-**Important for ASR Setup:** Speaker diarization requires a Hugging Face token and accepting terms for gated models (pyannote). If you encounter issues, check the ASR container logs with `docker logs whisper-asr-webservice` for troubleshooting.
-
-**For complete ASR setup instructions, model configurations, troubleshooting, and logs analysis, see the [Deployment Guide](DEPLOYMENT_GUIDE.md#advanced-asr-configuration)**
-
## Automated File Processing
Speakr includes a powerful "black hole" directory monitoring feature that automatically processes audio files without manual uploads. This is perfect for batch processing scenarios where you want to drop files into a directory and have them automatically transcribed.
@@ -437,149 +322,7 @@ Speakr includes a powerful "black hole" directory monitoring feature that automa
4. **Automatic Processing:** Files are moved to the uploads directory and processed using your configured transcription settings
5. **Database Integration:** Processed recordings appear in your gallery with the title "Auto-processed - [filename]"
-### Setup Instructions
-
-#### 1. Enable Auto-Processing
-
-Add these environment variables to your `.env` file:
-
-```dotenv
-# Enable automated file processing
-ENABLE_AUTO_PROCESSING=true
-
-# Directory to monitor (inside container)
-AUTO_PROCESS_WATCH_DIR=/data/auto-process
-
-# How often to check for new files (seconds)
-AUTO_PROCESS_CHECK_INTERVAL=30
-
-# Processing mode (see modes below)
-AUTO_PROCESS_MODE=admin_only
-```
-
-#### 2. Mount the Auto-Process Directory
-
-Update your `docker-compose.yml` to mount the auto-process directory:
-
-```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
- - ./auto-process:/data/auto-process # Add this line
-```
-
-#### 3. Create the Directory
-
-Create the auto-process directory on your host system:
-
-```bash
-mkdir auto-process
-```
-
-#### 4. Restart the Container
-
-```bash
-docker compose down
-docker compose up -d
-```
-
-### Processing Modes
-
-Speakr supports three different auto-processing modes:
-
-#### Mode 1: Admin Only (Default)
-```dotenv
-AUTO_PROCESS_MODE=admin_only
-```
-- All files in the main auto-process directory are assigned to the admin user
-- Simple setup, good for single-user scenarios
-
-#### Mode 2: User Directories
-```dotenv
-AUTO_PROCESS_MODE=user_directories
-```
-- Create subdirectories for each user: `auto-process/user123/` or `auto-process/123/`
-- Files are automatically assigned to the corresponding user
-- Example structure:
- ```
- auto-process/
- ├── user1/ # Files for user ID 1
- ├── user5/ # Files for user ID 5
- └── 123/ # Files for user ID 123
- ```
-
-#### Mode 3: Single User
-```dotenv
-AUTO_PROCESS_MODE=single_user
-AUTO_PROCESS_DEFAULT_USERNAME=john_doe
-```
-- All files are assigned to a specific username
-- Useful when you want all auto-processed files to go to a specific non-admin user
-
-### Supported File Formats
-
-The auto-processor supports the same audio formats as manual uploads:
-- **Common formats:** MP3, WAV, M4A, FLAC, AAC, OGG, WebM
-- **Mobile formats:** AMR
-
-**File Processing:**
-- **Supported formats** (MP3, WAV, FLAC, WebM, M4A, AAC, OGG) are processed directly without conversion
-- **Unsupported formats** are automatically converted to 32kbps MP3 using ffmpeg for optimal size/quality balance
-
-### Usage Examples
-
-#### Basic Usage (Admin Mode)
-```bash
-# Copy files to the auto-process directory
-cp /path/to/meeting1.mp3 auto-process/
-cp /path/to/meeting2.wav auto-process/
-
-# Files will be automatically processed within 30 seconds (default interval)
-```
-
-#### User Directory Mode
-```bash
-# Create user directories
-mkdir -p auto-process/user1
-mkdir -p auto-process/user5
-
-# Drop files for specific users
-cp meeting_with_john.mp3 auto-process/user1/
-cp team_standup.wav auto-process/user5/
-```
-
-#### Batch Processing
-```bash
-# Process multiple files at once
-cp /recordings/*.mp3 auto-process/
-cp /meetings/2024-01/*.wav auto-process/
-```
-
-### Monitoring and Logs
-
-Check the container logs to monitor auto-processing activity:
-
-```bash
-docker logs speakr -f
-```
-
-You'll see log entries like:
-```
-File monitor started in 'admin_only' mode, watching: /data/auto-process
-Found new audio file for user 1: /data/auto-process/meeting.mp3
-Copied /data/auto-process/meeting.mp3 to /data/uploads/auto_20250119021530_meeting.mp3
-Created recording record with ID: 123 for user: admin
-Started background processing for recording ID: 123
-```
+**For detailed instructions on setting this up, see the [Deployment Guide](DEPLOYMENT_GUIDE.md#automated-file-processing-black-hole-directory)**
</details>