Skip to content

feat: ffmpeg CLI fallback for MKV/WebM/OGG support#22

Merged
pasrom merged 6 commits intomainfrom
feat/ffmpeg-fallback
Mar 15, 2026
Merged

feat: ffmpeg CLI fallback for MKV/WebM/OGG support#22
pasrom merged 6 commits intomainfrom
feat/ffmpeg-fallback

Conversation

@pasrom
Copy link
Copy Markdown
Owner

@pasrom pasrom commented Mar 15, 2026

Summary

  • Add optional ffmpeg CLI integration as 3rd-tier audio loading fallback (AVAudioFile → AVAsset → ffmpeg)
  • FFmpegHelper detects ffmpeg binary via env var / common paths, cached at first access
  • Known ffmpeg-only extensions (MKV, WebM, OGG) short-circuit directly to ffmpeg, skipping Apple frameworks
  • File picker dynamically shows MKV/WebM/OGG when ffmpeg is detected
  • Settings → About shows ffmpeg availability status
  • Includes 5-minute timeout and proper stderr pipe cleanup

Test plan

  • 11 new tests in FFmpegHelperTests (detection, error descriptions, MKV/WebM/OGG loading, fallback chain, energy check, duration comparison)
  • Tests use pre-built two-speaker fixtures (German speech, transcribable by WhisperKit)
  • Tests XCTSkip when ffmpeg not installed
  • Full test suite passes (494 tests, 0 failures)
  • Lint clean
  • Manual: Settings → About → ffmpeg status (green/grey)
  • Manual: File picker shows MKV/WebM/OGG only when ffmpeg installed
  • Manual: MKV file transcribes successfully

What: 3-tier audio loading fallback: AVAudioFile → AVAsset → ffmpeg CLI.

New FFmpegHelper enum handles binary detection (cached via static let,
searches FFMPEG_BINARY env → /opt/homebrew/bin → /usr/local/bin →
~/.local/bin → /usr/bin) and audio extraction to 16kHz mono WAV.

AudioMixer.loadAudioAsFloat32() now catches AVAsset failures and falls
back to ffmpeg. New error cases: .ffmpegNotAvailable, .ffmpegFailed.
@github-actions github-actions bot added the enhancement New feature or request label Mar 15, 2026
pasrom added 5 commits March 15, 2026 16:14
File picker dynamically adds MKV/WebM/OGG when FFmpegHelper.isAvailable.
Settings → About shows ffmpeg status (green checkmark or grey "Not installed").
Tests detection, UTType registration, error descriptions, and
audio extraction from MKV/WebM (XCTSkip when ffmpeg not installed).
Replace on-the-fly ffmpeg conversion in tests with pre-built fixtures:
- sine_440hz_48k.mkv (H264 + AAC, 2ch, 48kHz)
- sine_440hz_48k.webm (VP9 + Opus, 2ch, 48kHz)
- sine_440hz_48k.ogg (Vorbis, 2ch, 48kHz)

Tests now cover all three formats individually, full fallback chain
for MKV and WebM, and energy verification. All XCTSkip when ffmpeg
not installed.
@pasrom pasrom force-pushed the feat/ffmpeg-fallback branch from f96ade4 to 07564a1 Compare March 15, 2026 15:15
@pasrom pasrom merged commit 7a38de5 into main Mar 15, 2026
4 checks passed
@pasrom pasrom deleted the feat/ffmpeg-fallback branch March 15, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant