Media Matcher

1. The Intelligence Engine (Matching Logic)

At the heart of Media Matcher is the Hungarian Algorithm (Kuhn-Munkres solver). Unlike simple one-to-one comparisons, Media Matcher builds a global cost matrix across all imported assets. It then solves for the configuration that minimizes the total distance sum, ensuring that even in complex datasets with hundreds of similar files, the overall assignment is mathematically optimal.

• Match Sensitivity: A granular percentage-based threshold (50% to 99%) allows users to define how strict the engine should be.
• FCPXML Support: By importing an FCPXML timeline, the app automatically crawls and loads every referenced asset, eliminating the need for manual folder selection for sources.

2. Multi-modal Fingerprinting & Analysis

Analysis is performed in a background-detached, non-blocking environment to keep the UI fluid.

• Video: Extracts frame samples at calculated intervals, downsampling them to 32x32 for memory efficiency while preserving sufficient detail for accurate comparison.
• Audio: Uses a single-pass streaming RMS envelope extraction. It generates two layers: a high-resolution buffer for matching and a 1000-point buffer for UI visualization.
• Images: High-quality downsampling for rapid visual matching.
• Persistent Caching: Fingerprints are stored in a thread-safe JSON cache. If you re-import a library, Media Matcher bypasses analysis and restores data instantly.

3. Accelerated Performance (vDSP)

Matching large libraries requires heavy calculation. Media Matcher utilizes Apple's Accelerate framework to perform vectorized SIMD (Single Instruction, Multiple Data) operations. By converting pixel buffers to floating-point values and using vDSP functions, the app calculates pixel distances at near-hardware speeds, making the "Match" phase significantly faster than standard loops.

4. Advanced Verification Tools

Once matches are found, editors need absolute certainty before finalizing.

• Overlay Comparison: Layers the "To Match" video over the original with 50% opacity.
• Difference Mode: A specialized blend mode that subtracts pixel values. In a perfect match, the screen will be black; any grading shifts or alignment slips appear as glowing discrepancies.
• Synchronized Waveforms: High-performance Canvas rendering of audio envelopes. Playheads are synchronized across all layers, and clicking the waveform allows for instant seeking.

5. Non-Destructive Asset Management

Media Matcher offers two primary ways to finalize a project:

• Collect in Destination: Moves matching assets to a new location.
• Overwrite & Backup (Pro Workflow): Replaces original files directly at their source. To ensure safety, it creates a structured backup: Media Matcher Backups/[FileName]/[Timestamp]/[OriginalFile]. The matched file is then copied to the original location with the original filename. This is entirely non-destructive and reversible.

6. Robustness & Stability

Designed for the rigors of professional use:

• Data Race Prevention: Video analysis uses NSLock and atomic collection to handle asynchronous frame generation across multiple threads.
• Error Transparency: If a file fails analysis (corrupt codec, permission issues), the app displays a specific warning and error message directly in the UI row, rather than failing silently.
• Adaptive Memory Management: Uses lazy loading for media players and low-resolution fingerprinting to maintain a small memory footprint even with 4K/8K assets.