WaveformMatcher

macOS app that matches video clips to audio WAV files by comparing waveforms, then exports a ready-to-import FCPXML for Final Cut Pro.

Features

• Waveform matching — compares audio fingerprints between video and WAV files to find sync points automatically
• Timecode matching — aligns clips using embedded timecode when available
• Manual sync mode — opens clips directly in Manual Sync without running waveform or timecode first
• Experimental Detect Slate guide — finds likely slate visible ranges, visual clap guides, and audio clap candidates; saves results in .wmproj and can apply them with Use Detect Slate
• Manual sync — video and audio marks can be set manually for sync offset review
• Lock Sync — setting both video and audio marks auto-locks the sync offset; shows ✓ Synced in green; supports Undo
• Export modes
  • Sync Clips — one <sync-clip> per matched pair
  • Multicam — one <multicam> per WAV file with all matching cameras as angles
• Timeline-aware parsing — supports Event XML, split timeline cuts, separate timeline clips, connected audio, and primary storyline audio
• Metadata — round-trips FCP studio tags (reel, scene, shot, camera angle, keywords) from source FCPXML
• Auto Speed — one-click button calculates playback speed from recorded frame rate metadata (recFPS ÷ timelineFPS); requires Shot Notes X or camera-embedded Rec FPS field
• Export Original Clips — optionally export original (unsynced) clips in a separate FCP event alongside synced output
• Export Video Speed Duplicate — for speed-adjusted clips, exports an additional 1× copy named with the recorded FPS (e.g. "48FPS")
• Frame-accurate multicam — mc-angle source clips are snapped to the timeline frame grid, eliminating FCP "not on edit frame boundary" warnings
• Export controls — Trim To Video Area and Spatial Conform (Fit / Fill) for Sync Clip and Multicam workflows
• Drag-and-drop FCPXML — drag an FCPXML file directly onto the Import button to load it
• Final Cut Pro Workflow Extension — accept direct Event/Timeline drag and drop from Final Cut Pro, plus dropped .fcpxml / .fcpxmld files, and open them in WaveformMatcher
• Send To Final Cut Pro — reopen generated FCPXML results in Final Cut Pro from the app
• Project files — save and restore the full project state (clips, settings, match results) in a .wmproj file via File > New / Open / Save / Save As
• Languages — English and Thai
• Update notifications — checks for new versions on launch and alerts the user with a download link

Requirements

• macOS 14.0+
• Final Cut Pro (to import the exported FCPXML)

Installation Note

This app is not notarized with Apple. On first launch, macOS Gatekeeper may block it.

Option 1 — Right-click to open: Right-click WaveformMatcher.app → Open → click Open in the dialog.

If macOS still blocks the app, go to System Settings → Privacy & Security and click Open Anyway.

Option 2 — Use Sentinel (friendlier quarantine helper): Advanced users can use Sentinel to remove the quarantine flag from apps they trust. This is optional and should only be used after downloading WaveformMatcher from this official repository.

Option 3 — Remove quarantine flag via Terminal:

xattr -dr com.apple.quarantine /Applications/WaveformMatcher.app

Architecture

File	Role
AudioMatcher.swift	Waveform fingerprinting and correlation via native audio extraction
FCPXMLParser.swift	Parses source FCPXML — extracts clips, timecode, metadata
FCPXMLGenerator.swift	Builds output FCPXML (sync-clip / multicam)
FCPXMLValidator.swift	Validates generated XML against FCP schema
TimecodeEngine.swift	Timecode arithmetic and frame conversion
ManualSyncView.swift	Dual-player sync viewer (AVPlayer + JKL)
VideoFullscreenPanel.swift	Fullscreen video panel
WaveformProject.swift	Project save/load (JSON)
Models.swift	Shared enums and data structures
Localization.swift	English / Thai string lookup
AppDelegate.swift	App lifecycle + launch-time update check
UpdateChecker.swift	Fetches latest release from GitHub and prompts user to download
SlateGuideDetector.swift	Experimental slate video/audio guide detection
SlateGuideTypes.swift	Shared models for slate guide results

Documentation

• Changelog
• User Manual (English source)
• คู่มือการใช้งาน (ภาษาไทย)
• Release Website
• User Manual PDF

1.4.2 Release Notes

Highlights in 1.4.2:

• Detect Slate now saves visible ranges, visual/audio guides, and debug candidates in .wmproj
• Use Detect Slate can apply saved slate guides as marks before Lock Sync
• Pressing Detect Slate again on an already-analyzed clip jumps back to the saved guide instead of re-analyzing
• Manual Sync restores slate ranges while switching clips and shows the primary range on the video seek bar
• Video seek bar zoom/pan and clearer Detect Slate progress make slate review easier
• .wmproj files are registered as WaveformMatcher project files for Finder open support

Releases

Source code is maintained in this repository.

Release artifacts and the public download page live in this repository.

The GitHub Pages release website is published from docs/.

Releasing a new version

1. Bump CURRENT_PROJECT_VERSION and MARKETING_VERSION in Xcode build settings
2. Commit, tag, and push:

   git tag vX.X && git push origin main && git push origin vX.X

3. Build a signed Release app and DMG with the release script:

   ./scripts/build_release_dmg.sh

   This script builds from the Xcode Release configuration with code signing enabled so the exported app keeps its sandbox entitlements.
4. Refresh the public docs and user manual PDF:

   python3 scripts/generate_user_manual_pdf.py

5. Create the GitHub release in this repository and upload the generated DMG:

   gh release create vX.X WaveformMatcher-X.X.dmg \
     --title "Version X.X"

Contributing

Contributions are welcome.

Recommended workflow:

1. Fork the repo and create a focused branch
2. Build locally with Xcode or:

   xcodebuild -project WaveformMatcher.xcodeproj -scheme WaveformMatcher -sdk macosx build CODE_SIGNING_ALLOWED=NO

3. Keep large local assets out of git:
   • ffprobe
   • rtdetr-*.pt
   • local datasets and generated release artifacts
4. If you touch user-facing behavior, update:
   • localization strings
   • user manual source in docs/
   • website assets in docs/ when relevant
   • CHANGELOG.md
5. Open a pull request with a short testing note

Dependencies

• ffprobe — optional fallback for raw-file timecode reads when FCPXML/native data is insufficient The app can now install FFprobe on demand when a timecode workflow truly needs it.

Acknowledgements

• FFmpeg / ffprobe — audio and video processing; licensed under LGPL 2.1+

---

Built with the assistance of Claude Code and Codex