7.0 KiB

Raw Blame History

Audio Transcription Desktop — Milestone 1 Design

Goal

Build the first milestone of a Windows 11 desktop application for preparing large audio and video files for transcription with the OpenAI Audio Transcription API. This milestone establishes a clean, testable foundation and a working native-looking GUI. It does not upload media or perform transcription yet.

Scope

Milestone 1 will:

accept one local audio or video file through a file picker or drag and drop;
display the file name, byte size in human-readable form, duration, and audio codec when available;
detect ffmpeg and ffprobe on PATH;
provide settings for an OpenAI API key, preferred transcription model, language (default pt-BR), and output directory;
store the API key through Python keyring, using Windows Credential Manager on Windows;
persist only non-secret settings in a per-user JSON configuration file;
provide a prominent Transcribe button whose action is explicitly stubbed;
display useful status and error messages inside the application;
include setup documentation, dependency declarations, automated unit tests, and a headless GUI startup check.

Out of scope are API uploads, media conversion, file splitting, transcription, retries, cost estimation, resumability, and transcript export. The architecture must leave clear seams for those later milestones without implementing them prematurely.

Architecture

Use a small layered src package:

app.py: application bootstrap and dependency wiring.
ui/: PySide6 windows, dialogs, widgets, and GUI-specific worker orchestration.
services/media_probe.py: executable detection and safe ffprobe invocation.
services/settings.py: non-secret settings loading, validation, and persistence.
services/credentials.py: API-key access through keyring only.
services/transcription.py: a typed milestone-1 interface that reports transcription as not yet implemented.
models.py: typed data structures shared across boundaries.
formatting.py: presentation-neutral size and duration formatting helpers.

The UI may depend on service interfaces and models. Services must not import UI modules. Business behavior will remain callable and testable without creating a Qt application.

User Interface

The main window will use standard PySide6 widgets and the platform style. It will contain:

A large file-selection/drop area with a Browse button.
A compact metadata panel showing filename, size, duration, and audio codec.
A visible FFmpeg/ffprobe availability status.
A Settings button opening a simple modal dialog.
A large Transcribe button.
A read-only status/log panel with timestamps or clear ordered messages.

The settings dialog will contain:

a masked API-key field;
a preferred-model editable field;
a language field initialized to pt-BR;
an output-directory field and folder picker;
Save and Cancel actions.

Saving will write the API key through the credential service and persist the other fields through the settings repository. An empty API-key field will preserve an existing stored key unless the UI explicitly indicates removal; milestone 1 does not require a credential-removal feature.

Data Flow

At startup, the application loads non-secret settings, checks whether a credential exists, detects ffmpeg and ffprobe, and reports readiness in the UI.

When a user selects or drops a file, the UI validates that it is a local file and starts media probing off the GUI thread. The media service invokes ffprobe with a bounded timeout and JSON output, then maps the result into a typed MediaInfo value. The UI displays the result and records status. Stale results from an earlier selection must not overwrite a newer selection.

When Transcribe is clicked, the UI checks that a valid file is selected and that required settings are present. It then calls the milestone-1 transcription boundary, which returns or raises a specific not-implemented result. The UI logs a friendly message that transcription will be added in a later milestone.

Persistence and Security

The API key must never appear in the JSON configuration file, logs, exceptions shown to the user, or README examples. The credential service uses a stable application service name and account identifier with keyring; on Windows this resolves to Windows Credential Manager.

Model, language, and output directory will be stored in a JSON file below the platform-appropriate per-user application data location. Writes will replace the settings file safely to reduce corruption risk. Missing or malformed configuration will fall back to defaults and produce a non-fatal warning.

Error Handling

Expected failures will be converted to concise user-facing messages and detailed enough internal log entries without exposing secrets. Covered cases include:

missing ffmpeg or ffprobe;
nonexistent, unreadable, or non-file selections;
invalid drag-and-drop content;
ffprobe timeout, nonzero exit, malformed JSON, or missing audio stream;
inaccessible output directory;
settings read/write failure;
unavailable or failing credential backend;
unexpected errors during startup or user actions.

The app should remain usable after recoverable failures. Missing FFmpeg disables metadata probing but not file selection or settings editing.

Testing and Validation

Automated tests will cover:

FFprobe JSON parsing for audio-only and video-with-audio inputs;
behavior when duration or codec is unavailable;
executable detection and subprocess failure mapping using mocks;
size and duration formatting;
settings defaults, round-trip persistence, and malformed-file recovery;
proof that serialized settings contain no API key;
credential-service calls using a mocked keyring backend;
transcription stub behavior;
basic file validation.

A headless Qt smoke check using the offscreen platform will construct and close the main window. Static checks will at minimum compile all Python modules. The final validation will also check the actual local availability of Python, dependencies, FFmpeg, and ffprobe, and will launch the app briefly or run an equivalent controlled startup probe.

Packaging Readiness

The app will use a conventional src layout, explicit entry point, filesystem-safe resource handling, and dependencies compatible with later PyInstaller packaging. Producing a packaged executable is not part of milestone 1.

Defaults

Language: pt-BR.
Model: an editable current transcription-model default documented in the implementation and README.
Output directory: the user's Documents directory when available, otherwise the user's home directory.

Success Criteria

Milestone 1 is complete when the GUI starts on the target Python environment, accepts selection and drag/drop, shows available media metadata, accurately reports tool availability, persists non-secret settings, stores the API key only through keyring, handles expected errors without crashing, exposes a clearly stubbed Transcribe action, and passes the implemented automated and startup checks.

7.0 KiB Raw Blame History