> For the complete documentation index, see [llms.txt](https://docs.mikopbx.com/mikopbx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mikopbx.com/mikopbx/english/modules/miko/module-local-speech-to-text.md). # Local Transcription Local call transcription in MikoPBX: recordings remain within the PBX, recognition runs on a Mac worker, and completed transcripts are available in the module interface and through the API. The **Local Speech To Text** module recognizes speech in recorded MikoPBX calls and saves the completed transcript as a conversation. Audio files are not sent to external cloud services: the PBX creates a job queue, while a separate **Local STT Worker** application downloads the assigned recording, recognizes it locally with the Parakeet or WhisperKit engine selected in MikoPBX, and returns the result to MikoPBX. {% hint style="info" %} The PBX module runs inside MikoPBX. The separate Local STT Worker application is available for Apple silicon Macs. See [Local STT Worker](/mikopbx/english/modules/miko/module-local-speech-to-text/miko-ai-worker.md) for a detailed description of the application. {% endhint %}

### How processing works 1. A call ends, and MikoPBX saves the call recording. 2. The module's background process finds the recording and creates a job. 3. Local STT Worker acquires a lease for the job. 4. The PBX provides the assigned recording file to that worker. 5. The worker prepares the audio, starts the engine and Core ML model specified in the job, and produces transcript segments. 6. The module filters the result, saves the transcript, and publishes an event for integrations. If the worker stops renewing its lease, the job returns to the queue. ### Requirements and compatibility * MikoPBX **2025.1.1** or later. * macOS **14.0** or later on a Mac with Apple silicon. * Call recording enabled for the required routes, queues, or extensions. * Network access from the Mac to the MikoPBX web interface. * Internet access for the first download of the selected model and its supporting files. After the model has been downloaded, the worker only needs access to the PBX for processing. ### Installing the module 1. Open the MikoPBX web interface. 2. Go to **Modules** → **Module marketplace**.

3. Find **Local Speech To Text** and install it. 4. Open the **Installed modules** tab and enable the module.

5. Click the settings button to the right of the module version.

### Settings tab | Setting | Default | Purpose | | ------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- | | **Default language** | Detect automatically | Language hint for the recognition engine. In automatic mode, the worker detects the language from the result. | | **Base poll interval, sec.** | `30` | Interval for scanning new CDR records. Range: `30`–`3600`. | | **Maximum recognizable recording duration, min.** | `60` | Recordings with a known duration above this limit are skipped. Range: `1`–`1440`. | | **CDR per scan** | `50` | Number of CDR records checked in one cycle. Range: `1`–`1000`. | | **Job timeout, sec.** | `1800` | Lease lifetime without a successful renewal. Range: `60`–`86400`. | | **Recording processing window** | `30 days` | How far back to search for completed calls with recordings: 1, 7, 30, 90, 180, or 365 days, or all recordings. | | **Transcript retention** | `1 year` | When transcription results are deleted: after 30, 90, 180, or 365 days, or never. | | **Recognition terms** | Empty | Company, product, and system names, plus other words used as recognition hints. | The recording processing window cannot exceed the transcript retention period. Retention starts when recognition completes; CDR records and source audio recordings are not deleted. {% hint style="info" %} Changing the recording processing window resets the scan cursor so that the module reviews call history within the new range. {% endhint %}

#### Recognition terms Enter terms separated by commas, semicolons, or new lines, or upload them from a TXT file. The module removes duplicates and sends the worker up to 100 terms, each no longer than 120 characters. The **Download template** button saves a sample TXT file.

#### Audio processing parameters WhisperKit model decoding parameters, normalization, VAD, maximum segment duration, and overlap are stored centrally in MikoPBX and sent to registered workers. In the current version, the advanced block containing these parameters is hidden, so they cannot be configured through either the module or worker interface. ### Model marketplace tab This tab selects the model that the PBX includes in new jobs. The selection applies centrally to all workers and appears in Local STT Worker after its settings synchronize. {% hint style="warning" %} Parakeet supports 25 languages: Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Russian, and Ukrainian. Select a WhisperKit model before processing calls in another language. {% endhint %} | Model | When to choose it | Characteristics | | -------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ | | **Parakeet TDT 0.6B v3** | Most calls | Default model. Fast recognition of long-form speech in 25 languages through the Parakeet engine. | | **Whisper Large V3 Turbo** | You want a proven general-purpose model | A good balance of speed and quality for typical multilingual calls through WhisperKit. | | **Whisper Podlodka Turbo** | Almost all conversations are in Russian | A Whisper model fine-tuned for Russian speech from `smkrv/whisper-podlodka-turbo-coreml`. | | **Whisper Large V3** | Quality matters more than speed | The heaviest model in the catalog for difficult or unclear recordings. Runs through WhisperKit. | After selecting a model, click **Save model**.

#### Catalog contents The catalog contains only the four reviewed models listed above. Adding arbitrary custom repositories through the interface is no longer supported: the worker accepts only the engine and Core ML artifact combinations provided by the module. {% hint style="warning" %} Previously saved custom models do not extend the current catalog. After upgrading, select one of the supported models and save the selection. {% endhint %}

### Queue tab | Status | Meaning | | ------------------------------ | ----------------------------------------------------------------------- | | **Pending** | The job is waiting for an available worker. | | **Processing** | The job is assigned to a worker under an active lease. | | **Done today** | Jobs completed during the current day. | | **Errors** | Failed jobs that can be returned to the queue. | | **Waiting for recording file** | A CDR record was found, but the file has not appeared or is unreadable. | | **Skipped recordings** | Recordings that will not be processed unless the conditions change. | Reasons for skipping include exceeding the maximum duration, being unable to verify the duration of a recording that appears too long in the CDR, exceeding the fixed 500 MiB limit, a missing file after the waiting period expires, and a call falling outside the processing window. An unknown or zero CDR duration does not by itself prevent the module from creating a job. When the CDR duration exceeds the limit, the module verifies the media file duration with a time-limited `ffprobe` process.

### Workers tab Use this tab to create access keys, view registered Macs, and check their compatibility. A key is shown only once after it is created. A single key cannot be bound to multiple `worker_uid` values at the same time; create a separate key for each Mac. After deleting a key, register the associated worker again with a new token. The worker table shows the name, UID, IP address, model selected in MikoPBX, application version, status, and last activity. Worker API version and compatibility are no longer separate columns. An incompatible worker appears offline; the update guide link remains below the table. The top of the tab includes a download section for the macOS application. Until a build is published there, the download button remains unavailable.

### Transcripts tab You can filter the list by call date range. The table shows the date, `call_id`, job number, file, language, duration, model, and time when the result was created. The conversation view includes a player and recording download, timestamped turns, separate channel columns for stereo recordings, grouped diagnostics, raw technical information, and transcript JSON. Clicking a turn moves the player to the corresponding point in the recording.

### Logging tab The log contains structured technical events from the module and workers, without transcripts, audio recordings, or secrets. Available periods are `1h`, `3h`, `12h`, `1d`, and the entire log. You can filter by level and component, perform a full-text search, and refresh the list. The interface displays no more than the latest 1,000 matching events. ### Updating the module and worker When moving to Worker API v2, update the components in this order: 1. Update ModuleLocalSpeechToText to version 1.45. 2. Older workers temporarily become incompatible and offline; active v1 leases return to the queue without increasing the attempt count. 3. Update Local STT Worker to version 1.7 build 34. 4. Open **Diagnostics** or **Settings** in the worker and run the connection check again. The queue, completed results, settings, worker UIDs, and existing API keys are preserved. This transition does not require a MikoPBX Core version newer than 2025.1.1. ### REST API Base path: ``` /pbxcore/api/v3/module-local-speech-to-text ``` #### Transcripts for integrations * `GET /transcripts?limit=50&offset=0&date_from=YYYY-MM-DD&date_to=YYYY-MM-DD` * `GET /transcripts/{result_id}` * `GET /transcripts/events?cursor=created_at:event_id&limit=100` * `GET /call-transcripts/{call_transcript_id}?revision={revision}` * `GET /call-transcripts/events?cursor={cursor}&limit=100` `transcripts/events` publishes idempotent `transcript.completed` events. A detailed transcript contains stable `segment_id` values, source segments, merged `turns`, and plain text. `call-transcripts` combines multiple recordings from one logical call into a versioned transcript. Its part manifest preserves `cdr_start_ms` and `cdr_end_ms`, while segments contain relative and absolute timestamps. Adjacent segments from the same participant and channel are combined into a single turn without losing their source `segment_id` values. #### Worker API v2 The worker first calls `GET /worker-api-contract`, then sends the `X-MikoPBX-Worker-API-Version: 2` header with every Worker API request. The `GET /worker-processing-settings` response contains the centralized processing profile and a `selected_model` object with the model identifier, repository, engine, Core ML artifact type, and display name. Jobs also contain `model_engine` and `model_artifact_type`, which the worker uses to choose Parakeet or WhisperKit. Arbitrary engine, model, and artifact combinations are rejected. | Operation | Endpoint | | ------------------ | --------------------------------- | | Registration | `POST /workers` | | Processing profile | `GET /worker-processing-settings` | | Acquire lease | `POST /job-leases` | | Download recording | `GET /job-recordings/{job_id}` | | Renew lease | `PATCH /job-leases/{job_id}` | | Release lease | `DELETE /job-leases/{job_id}` | | Submit result | `PUT /job-results/{job_id}` | | Submit failure | `PUT /job-failures/{job_id}` | Legacy Worker API v1 endpoints have been removed. Local STT Worker 1.7 does not fall back to v1 and stops with upgrade guidance when it encounters an incompatible module version. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mikopbx.com/mikopbx/english/modules/miko/module-local-speech-to-text.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.