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.mdindex 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 ProcessingSpeakr 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 automa4. **Automatic Processing:** Files are moved to the uploads directory and processed using your configured transcription settings5. **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>