File & URL Transcription
Relevant source files
The following files were used as context for generating this wiki page:
File & URL Transcription is a core capture mode in MacParakeet that allows users to convert local media files and remote web content into text. It supports a wide array of formats, including audio and video files, and leverages yt-dlp to process URLs from platforms like YouTube, X, Vimeo, and Apple Podcasts. All speech-to-text (STT) processing for this feature occurs locally on the user's Mac using the Parakeet TDT engine via FluidAudio CoreML.
The system is designed for high performance, achieving approximately 155x real-time speed on Apple Silicon, and prioritizes privacy by keeping audio data on-device. Once transcribed, results are stored in a local SQLite database for history management and can be exported into multiple formats such as Markdown, SRT, and PDF.
Sources: spec/00-vision.md, README.md:95-102, spec/05-audio-pipeline.md:36-40
Architecture and Data Flow
The transcription pipeline follows a multi-stage process involving ingestion, normalization, speech recognition, and final artifact generation.
Local File Transcription Flow
When a user drops a local file, the system probes the media using FFmpeg to validate the format and duration. It then normalizes the audio to a specific format required by the STT engine.
The system normalizes all input categories (Audio/Video) to 16kHz mono Float32 WAV files before they reach the speech engine.
Sources: spec/05-audio-pipeline.md:46-73
URL Transcription Flow
URL transcription integrates yt-dlp to handle remote media. It fetches audio-only streams and optional video metadata (thumbnails, channel names) to enrich the library view.
For YouTube specifically, the system can extract HLS streaming URLs for video playback without downloading the full video file, saving local storage.
Sources: spec/05-audio-pipeline.md:75-107, plans/completed/2026-03-video-player-and-transcription-ui-revamp.md:213-225
Supported Media Formats
MacParakeet supports a comprehensive list of categories for local file transcription:
| Category | Formats |
|---|---|
| Audio | MP3, WAV, M4A, FLAC, OGG, OPUS |
| Video | MP4, MOV, MKV, WebM, AVI |
Sources: spec/05-audio-pipeline.md:52-57
Components and Data Models
Transcription Model
The Transcription model is the primary data structure for storing results. Following the 2026-03 UI revamp, it was expanded to include video-specific metadata.
thumbnailURL: Local path or remote URL for visual representation.channelName: The uploader or channel identifier for web sources.videoDescription: Used to provide additional context to LLMs.speakerId: Assigned toWordTimestampduring the diarization phase.
Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md:105-115, plans/completed/2026-03-speaker-diarization.md:37-45
Speaker Diarization
Diarization is an optional but default phase for file and URL transcription (can be skipped by holding the Option key). It uses a sequential pipeline:
- ASR (Speech Recognition): Generates word-level timestamps.
- Diarization: Identifies speaker segments (e.g., "S1", "S2").
- SpeakerMerger: A pure function that assigns
speakerIdto words based on temporal overlap.
Sources: plans/completed/2026-03-speaker-diarization.md:14-25, plans/completed/2026-03-speaker-diarization.md:147-160
Playback and Visualization
The system provides two distinct modes for interacting with transcribed media:
- Video Mode: A 40/60 split-pane view with an
AVPlayeron the left and transcript/chat on the right. This is used for YouTube URLs and local video files. - Audio Mode: A full-width content view featuring a persistent ~44px horizontal scrubber bar at the top, used for audio-only files.
Both modes support Synced Transcript Highlighting, where the current segment is highlighted and auto-scrolled into view based on currentTimeMs from the player.
Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md:280-315, plans/completed/2026-03-video-player-and-transcription-ui-revamp.md:345-355
Export Engine
The ExportService handles the transformation of Transcription objects into user-facing artifacts. It supports several industry-standard formats.
| Format | Features |
|---|---|
| TXT / Markdown | Supports metadata, timestamps, and speaker labels. |
| SRT / VTT | Subtitle formats; cues are split at speaker boundaries and punctuation. |
| JSON | Full data dump including word-level confidence and diarization segments. |
| PDF / DOCX | Rich text exports using AppKit's layout managers for pagination and styling. |
Sources: Sources/MacParakeetCore/Services/ExportService.swift:7-22, Sources/MacParakeetCore/Services/ExportService.swift:233-255
// Example of subtitle cue building logic in ExportService.swift
public func buildSubtitleCues(from words: [WordTimestamp]) -> [SubtitleCue] {
// Rules: max ~12 words per cue, break on sentence-ending punctuation,
// break on long pauses (>800ms), max ~7 seconds per cue, break on speaker change.
TranscriptCueBuilder.build(from: words)
}
Sources: Sources/MacParakeetCore/Services/ExportService.swift:356-361
Conclusion
File & URL Transcription in MacParakeet is a robust system that combines local performance with broad web compatibility. By leveraging yt-dlp for ingestion and a dedicated ExportService for output, it provides a seamless workflow from raw media to structured, speaker-labeled text. Its architecture ensures that even complex tasks like HLS video streaming and multi-speaker diarization are handled while maintaining a local-first privacy posture.