Output Format Writers
Relevant source files
The following files were used as context for generating this wiki page:
The Output Format Writers module in mlx-qwen3-asr provides a specialized suite of utilities for persisting transcription results into various standardized file formats. This system translates the internal TranscriptionResult data structure into user-consumable formats such as plain text, structured JSON, and timestamped subtitle files (SRT and WebVTT).
These writers are primarily utilized by the Command Line Interface (CLI) and the high-level transcription pipeline to ensure that generated speech-to-text data is accurately formatted for downstream applications, such as video editing, meeting documentation, and data analysis.
Sources: mlx_qwen3_asr/writers.py:1-7, mlx_qwen3_asr/cli.py:539-550, CLAUDE.md:104-104
System Architecture and Data Flow
The output system operates by taking a finalized TranscriptionResult object and passing it to a specific writer function determined by the user's requested format. The get_writer function acts as a factory, returning the appropriate callable for the target format.
Transcription Data Flow
The following diagram illustrates how raw transcription data is processed and routed through the writers.
This flow ensures that the core transcription logic remains decoupled from specific file formatting requirements.
Sources: mlx_qwen3_asr/writers.py:100-118, mlx_qwen3_asr/cli.py:516-522
Supported Formats
The system supports five primary output formats, each catering to different use cases.
| Format | Function | Description | Required Data |
|---|---|---|---|
| txt | write_txt | Simple plain text file containing only the transcribed text. | result.text |
| json | write_json | Complete metadata export including language, segments, and speaker info. | result object |
| srt | write_srt | Standard SubRip subtitle format with HH:MM:SS,mmm timestamps. | result.segments |
| vtt | write_vtt | WebVTT subtitle format with HH:MM:SS.mmm timestamps. | result.segments |
| tsv | write_tsv | Tab-separated values with start, end, and text columns. | result.segments |
Sources: mlx_qwen3_asr/writers.py:23-97, mlx_qwen3_asr/cli.py:461-465
Subtitle Generation Logic
For subtitle formats (SRT and VTT), the system employs a sophisticated grouping algorithm called group_subtitle_segments. This function transforms raw word-level or short-phrase segments into readable subtitle blocks based on several configurable constraints.
Subtitle Grouping Constraints
The grouping logic respects specific technical and readability limits to ensure subtitles are not too long or too fast for viewers.
- Max Words: Groups up to 10 words per subtitle block.
- Max Characters: Limits blocks to approximately 42 characters.
- Duration: Prevents subtitle blocks from exceeding 6.0 seconds.
- Gaps: Forces a break if a temporal gap of 0.8 seconds or more is detected between segments.
- Sentence Boundaries: Automatically breaks segments at sentence-ending punctuation (
.,!,?,。,！,？).
Sources: mlx_qwen3_asr/writers.py:121-175
Timestamp Formatting
Different formats require specific timestamp syntaxes. The internal helpers _format_timestamp_srt and _format_timestamp_vtt handle these conversions.
# SRT uses a comma for milliseconds
# Sources: [mlx_qwen3_asr/writers.py:207-212]
def _format_timestamp_srt(seconds: float) -> str:
return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
# VTT uses a dot for milliseconds
# Sources: [mlx_qwen3_asr/writers.py:215-220]
def _format_timestamp_vtt(seconds: float) -> str:
return f"{hours:02d}:{minutes:02d}:{secs:02d}.{millis:03d}"
Language-Specific Formatting
The writers include specialized logic for CJK (Chinese, Japanese, Korean) languages. When joining subtitle tokens, the system detects if the language is a CJK variant and modifies the joining behavior.
- Non-CJK: Tokens are joined with spaces, and specific regex rules are applied to clean up whitespace around punctuation.
- CJK: Tokens are joined directly without spaces to match standard typographic conventions for these languages.
Sources: mlx_qwen3_asr/writers.py:186-204
CLI Integration
The CLI provides a unified interface for selecting these formats via the --output-format (or -f) flag. Users can also specify --output-format all to generate every supported format simultaneously.
Subtitle Auto-Enabling
The CLI contains "pre-flight" logic that identifies if a subtitle format is requested. If so, it automatically enables timestamp generation (return_timestamps=True) in the transcription pipeline, as SRT/VTT files cannot be generated without word-level timing data.
Sources: mlx_qwen3_asr/cli.py:516-532, examples/real-world/README.md:11-13
Summary
The Output Format Writers module is a critical component for the usability of mlx-qwen3-asr. By providing robust, configurable grouping logic and support for industry-standard formats, it allows the project to bridge the gap between raw model inference and practical, human-readable documentation and media accessibility.