Voice Transcriptor

Windows desktop application for resumable OpenAI transcription of long audio and video recordings.

Setup and run

Install Python 3.12 or newer plus FFmpeg/FFprobe, ensure both executables are on PATH, then install dependencies and launch:

python -m pip install -r requirements.txt
python -m voice_transcriptor

The app accepts .m4a, .mp3, .wav, .mp4, .mov, .webm, and .mkv. It probes the source with FFprobe and streams it through FFmpeg into mono 24 kHz AAC-LC .m4a chunks at 64 kbps. Video audio is selected directly, with no large intermediate extraction file.

Chunking is duration-based, not tied to a presumed universal upload-size limit. Defaults are 15-minute chunks with 15 seconds of overlap. Change duration, overlap, and temporary-file retention under Settings → Advanced.

Each transcription job is stored under <output directory>/voice-transcriptor-jobs/<job-id>/. Its atomic JSON manifest retains the exact source start/end time of every chunk plus pending, processing, completed, or failed status and raw transcript text. Successful chunks are saved immediately. Restarting the same source with the same effective settings resumes an incomplete job and never retranscribes completed chunks.

The default model is gpt-transcribe. Settings provides an editable selector seeded with gpt-transcribe, gpt-4o-transcribe, and gpt-4o-mini-transcribe, so future compatible transcription model IDs can be entered. The current official API documentation may reject gpt-transcribe for accounts where that identifier is unavailable; the application reports that as a permanent API error without silently changing models.

Language defaults to Brazilian Portuguese. The app sends ISO language pt and a prompt that preserves the spoken language without translation, Brazilian spelling and punctuation, numbers, names, technical terminology, and acronyms. Add names and specialized vocabulary in Settings → Context / Vocabulary.

Every preprocessed chunk is submitted independently to the OpenAI Audio Transcriptions API. Raw chunk transcripts are concatenated in source order; overlap deduplication is intentionally not implemented yet. Rate limits, timeouts, connection errors, and server errors use finite exponential backoff. Permanent API failures are not retried indefinitely. Active preprocessing, retry waits, and transcription can be cancelled without blocking the GUI.

API key

Store the API key as a Windows Credential Manager generic credential whose target name is exactly OPENAI_API_KEY. The application retrieves that existing target through the Windows keyring backend. Saving a replacement key from Settings updates the same target. API keys and authorization headers are never written to settings, job manifests, transcripts, or logs.

Tests

python -m pytest -v
python -m compileall -q src tests

Tests use fake API endpoints and do not make live OpenAI requests.