Skip to content

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

Python

Docs: reasoning settings, keyless local text models and Tencent Cloud ASR in the guides and README

Murtaza Nasir0a9227ca8af2
diff --git a/README.md b/README.md
index 4cf9c71a..0991ed16 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ Speakr turns a recording into organized, searchable, shareable knowledge. Here i
- **Hands-off intake** - a watched "black hole" folder auto-imports and processes any audio dropped into it, with optional per-user subfolders named by user id or username.
### Transcribe
-- **Bring your own engine** - self-hosted WhisperX (recommended; it is what enables the speaker features below), OpenAI, Mistral / Voxtral, AssemblyAI, OpenASR, Alibaba FunASR, or any custom ASR webservice. The right connector is auto-detected from your configuration.
+- **Bring your own engine** - self-hosted WhisperX (recommended; it is what enables the speaker features below), OpenAI, Mistral / Voxtral, AssemblyAI, Tencent Cloud ASR, OpenASR, Alibaba FunASR, or any custom ASR webservice. The right connector is auto-detected from your configuration.
- **Speaker diarization** - automatic who-said-what labeling (WhisperX, or OpenAI's diarizing models).
- **Voice profiles** - recognize the same person across different recordings via voice embeddings (requires the WhisperX ASR backend).
- **Custom vocabulary and hotwords** (most effective with the WhisperX backend) - bias the transcriber toward names, jargon, and acronyms it would otherwise mishear; configurable globally, per tag / folder, or right in the upload and in-app recording dialogs, with reusable saved templates.
@@ -148,7 +148,7 @@ docker compose up -d
**Required API Keys:**
- `TRANSCRIPTION_API_KEY` - For speech-to-text (OpenAI) or `ASR_BASE_URL` for self-hosted
-- `TEXT_MODEL_API_KEY` - For summaries, titles, and chat (OpenRouter or OpenAI)
+- `TEXT_MODEL_API_KEY` - For summaries, titles, and chat (OpenRouter or OpenAI; not needed for a local server without authentication)
### Transcription Options
@@ -162,6 +162,7 @@ Speakr uses a **connector-based architecture** that auto-detects your transcript
| **VibeVoice ASR** | Self-hosted (vLLM) | Yes (built-in) | No |
| **MOSI/Mossland MOSS** | Hosted API key | Yes (built-in) | No |
| **AssemblyAI** | Just API key | Yes (built-in) | No |
+| **Tencent Cloud ASR** | API keys (+ S3/COS bucket for files over 5 MiB) | Yes (built-in) | No |
| **OpenASR** | Self-hosted server | Yes (built-in) | No |
| **Alibaba FunASR** | API key + OSS bucket | Yes (built-in) | No |
| **Legacy Whisper** | Just API key | No | No |
@@ -209,6 +210,14 @@ TRANSCRIPTION_API_KEY=your-assemblyai-key
```
Handles multi-hour, multi-speaker files in a single job. New accounts get free credits with no card required.
+**Tencent Cloud ASR (Chinese and English meetings):**
+```bash
+TRANSCRIPTION_CONNECTOR=tencent_asr
+TENCENT_SECRET_ID=your-secret-id
+TENCENT_SECRET_KEY=your-secret-key
+```
+Files over 5 MiB are passed to Tencent through an S3-compatible bucket such as Tencent COS. See the [Tencent ASR guide](https://murtaza-nasir.github.io/speakr/advanced/tencent-asr) for engines and storage.
+
> **PyTorch 2.6 Users:** If you encounter a "Weights only load failed" error with WhisperX, add `TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=true` to your ASR container. See [troubleshooting](https://murtaza-nasir.github.io/speakr/troubleshooting#pytorch-26-weights-loading-error-whisperx-asr-service) for details.
**[View Full Installation Guide →](https://murtaza-nasir.github.io/speakr/getting-started/installation)**
diff --git a/docs/admin-guide/model-configuration.md b/docs/admin-guide/model-configuration.md
index c93745ec..5a449953 100644
--- a/docs/admin-guide/model-configuration.md
+++ b/docs/admin-guide/model-configuration.md
@@ -409,7 +409,7 @@ The name of the `chat_template_kwargs` field depends on the model's chat templat
# Required: API endpoint
TEXT_MODEL_BASE_URL=https://api.openai.com/v1
-# Required: API key
+# API key (can be left out for a local server without authentication)
TEXT_MODEL_API_KEY=your_api_key_here
# Required: Model identifier
diff --git a/docs/features.md b/docs/features.md
index 72473fb6..1a648969 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -32,7 +32,7 @@ Uploads of files larger than 16 MB are sent as fixed-size slices through the sam
### Multi-Engine Support
-Speakr supports multiple transcription engines to match your needs and budget. Use [OpenAI's Whisper API](getting-started.md#option-a-openai-whisper-configuration) for quick, cloud-based transcription with excellent accuracy. Deploy the [recommended ASR container](getting-started.md#option-b-custom-asr-endpoint-configuration) for advanced features like speaker diarization and local processing. Use [Mistral Voxtral](getting-started/installation.md#for-mistral-voxtral-cloud-based-diarization) for cloud-based diarization via the Mistral API, or run [VibeVoice ASR](getting-started/installation.md#for-vibevoice-asr-self-hosted-via-vllm) on your own hardware for fully self-hosted transcription with diarization. For long, multi-speaker meetings, [AssemblyAI](getting-started/installation.md#for-assemblyai-cloud-based-diarization) offers cloud diarization and handles multi-hour files in a single job. See the [installation guide](getting-started/installation.md) for detailed setup instructions. The system automatically handles different audio formats, converting them as needed for optimal transcription quality.
+Speakr supports multiple transcription engines to match your needs and budget. Use [OpenAI's Whisper API](getting-started.md#option-a-openai-whisper-configuration) for quick, cloud-based transcription with excellent accuracy. Deploy the [recommended ASR container](getting-started.md#option-b-custom-asr-endpoint-configuration) for advanced features like speaker diarization and local processing. Use [Mistral Voxtral](getting-started/installation.md#for-mistral-voxtral-cloud-based-diarization) for cloud-based diarization via the Mistral API, or run [VibeVoice ASR](getting-started/installation.md#for-vibevoice-asr-self-hosted-via-vllm) on your own hardware for fully self-hosted transcription with diarization. For long, multi-speaker meetings, [AssemblyAI](getting-started/installation.md#for-assemblyai-cloud-based-diarization) offers cloud diarization and handles multi-hour files in a single job. For Chinese and English meetings, [Tencent Cloud ASR](advanced/tencent-asr.md) provides recording-file recognition with speaker labels and hotwords. See the [installation guide](getting-started/installation.md) for detailed setup instructions. The system automatically handles different audio formats, converting them as needed for optimal transcription quality.
### Speaker Diarization
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 35e1dab2..6f617640 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -59,6 +59,8 @@ TEXT_MODEL_API_KEY=sk-your_openai_api_key
TEXT_MODEL_NAME=gpt-4o-mini
```
+A local server such as Ollama, vLLM or llama.cpp works as well: set `TEXT_MODEL_BASE_URL` to its address (for example `http://localhost:11434/v1`) and leave out `TEXT_MODEL_API_KEY` if the server needs no key. To change how much a model reasons, or to turn reasoning off, see [Provider-Specific Request Parameters](admin-guide/model-configuration.md#provider-specific-request-parameters).
+
For OpenAI's latest GPT-5 models (`gpt-5`, `gpt-5-mini`, `gpt-5-nano`), you must use the OpenAI API directly. See the [Model Configuration Guide](admin-guide/model-configuration.md) for detailed GPT-5 setup.
### Required: Transcription Service
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index baea328c..22b07050 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -110,9 +110,11 @@ TEXT_MODEL_API_KEY=sk-or-v1-your-key-here
TEXT_MODEL_NAME=openai/gpt-4o-mini
```
-If you prefer to use OpenAI directly for text generation, simply change the base URL to `https://api.openai.com/v1` and use your OpenAI API key. You can also use local models through Ollama or LM Studio by pointing to `http://localhost:11434/v1` or similar.
+If you prefer to use OpenAI directly for text generation, simply change the base URL to `https://api.openai.com/v1` and use your OpenAI API key. You can also use local models through Ollama, LM Studio, vLLM or llama.cpp by pointing to `http://localhost:11434/v1` or similar. A local server without authentication needs no key, so `TEXT_MODEL_API_KEY` can be left out.
-> **Tip:** For advanced model configuration options—including GPT-5 support, separate chat model settings for different service tiers, and cost optimization strategies—see the [Model Configuration](../admin-guide/model-configuration.md) guide.
+Many current models reason before they answer, which makes summaries and titles slower and, on paid services, more expensive. The reasoning effort, or whether the model reasons at all, can be set with `TEXT_MODEL_EXTRA_BODY`; the field to use differs by provider and model, as listed in [Provider-Specific Request Parameters](../admin-guide/model-configuration.md#provider-specific-request-parameters).
+
+> **Tip:** For advanced model configuration options—including GPT-5 support, reasoning settings for each provider, separate chat model settings for different service tiers, and cost optimization strategies—see the [Model Configuration](../admin-guide/model-configuration.md) guide.
#### For Legacy OpenAI Whisper API
@@ -236,7 +238,7 @@ Use `TRANSCRIPTION_CONNECTOR=tencent_asr` with `TENCENT_SECRET_ID` and
`TENCENT_SECRET_KEY`. This native connector supports Tencent recording-file
recognition, timestamps, speaker labels and hotwords, without an ASR bridge
container or local GPU. See the [Tencent ASR setup guide](../advanced/tencent-asr.md)
-for engines, large files, resource packages and retry limitations.
+for engines, large files, resource packages and how failed jobs are retried.
#### For AssemblyAI (Cloud-Based Diarization)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index f77e7331..6ba3aebb 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -116,6 +116,10 @@ Network speed affects transcription time since audio must upload to API services
The choice of transcription model impacts speed. Whisper Large is more accurate but slower than Whisper Base. If speed matters more than perfect accuracy, consider using a smaller model through your API settings.
+### Slow Summaries and Titles With a Reasoning Model
+
+Models that reason before answering, such as Qwen3, GPT-5 or DeepSeek, can take many times longer than the answer alone requires, and on paid services the reasoning tokens are billed as output. Summaries and titles rarely benefit from long reasoning. Lower the reasoning effort or turn reasoning off with `TEXT_MODEL_EXTRA_BODY`, using the field your provider accepts; see [Provider-Specific Request Parameters](admin-guide/model-configuration.md#provider-specific-request-parameters). Compare the response time or the token counts in the [system statistics](admin-guide/statistics.md) before and after the change, since some local servers ignore fields they do not recognise.
+
### Recordings Stuck After Restart
If Speakr crashed or restarted while recordings were processing, they automatically resume on next startup. The job queue persists to the database, so no uploads are lost. Check the logs for "Recovered orphaned jobs" messages confirming jobs were resumed.
@@ -167,7 +171,7 @@ Since v0.10.4-alpha the stock image runs threaded gunicorn workers (3 processes
### Chat Responses End Mid-Sentence
-If a chat or Inquire response stops abruptly with a note that the output token limit was reached, the model hit the configured `CHAT_MAX_TOKENS` ceiling (default 2000). This is common with reasoning models, whose hidden reasoning tokens share the same budget as the visible answer. Ask the model to continue from where it stopped, or raise `CHAT_MAX_TOKENS` in your `.env`. Before v0.10.3-alpha these truncated responses were displayed as if they had completed normally; they are now flagged explicitly.
+If a chat or Inquire response stops abruptly with a note that the output token limit was reached, the model hit the configured `CHAT_MAX_TOKENS` ceiling (default 2000). This is common with reasoning models, whose hidden reasoning tokens share the same budget as the visible answer. Ask the model to continue from where it stopped, raise `CHAT_MAX_TOKENS` in your `.env`, or lower the model's reasoning effort with `TEXT_MODEL_EXTRA_BODY` (or `CHAT_MODEL_EXTRA_BODY` for a separate chat model), as described in [Provider-Specific Request Parameters](admin-guide/model-configuration.md#provider-specific-request-parameters). Before v0.10.3-alpha these truncated responses were displayed as if they had completed normally; they are now flagged explicitly.
### Speaker Identification Not Working