Commentary Player - Enhanced

An advanced media player for synchronizing external commentary tracks with video.

Ever downloaded a Custom commentary, a fan analysis track, or an alternate language dub as a separate audio file? This application is the solution.

Commentary Player - Enhanced is a desktop media player purpose-built to load a video and a separate audio file, synchronize them perfectly, and play them together as a single, seamless experience.

It is designed for film enthusiasts, media archivists, content reviewers, and anyone who wants to enjoy supplemental audio content that isn't embedded in their primary video file.

Key Features

• Dual-Track Playback: Independently load a primary video file and a secondary audio (commentary) file.
• Manual Syncing & Linking: Use the independent controls to find the perfect synchronization point, then "link" the tracks.
• Automatic Drift Correction: Once linked, the player subtly adjusts the commentary's playback speed to ensure it stays perfectly in sync with the video, preventing audio drift over long durations.
• Chapter Navigation: Automatically detects and displays embedded chapter markers from the video file in a dedicated panel and as visual ticks on the seek bar for easy navigation.
• Advanced Media Support: Leverages FFmpeg and FFprobe to handle a wide variety of video formats, extract detailed metadata, and manage multiple embedded audio and subtitle tracks.
• Flexible Viewing Modes: Includes a standard windowed mode, a native fullscreen mode with auto-hiding controls, and a Picture-in-Picture (PiP) mode for watching video on top of other applications. With a always on top button in the PIP window
• Built-in GIF Creator: Instantly create a 10-second, high-quality GIF from the video at the current playback position, 
• Session Management: Save your entire setup—video file, commentary file, and the precise sync offset—to a single JSON session file and load it again later.

Why Use This Player?

1. The Ultimate Commentary Experience

This player unshackles commentary tracks from specific media releases, letting you mix and match any video with any commentary audio. It's built from the ground up to solve the common problem of having a commentary track you can't easily listen to while watching the corresponding film.

2. Precision Syncing, Made Effortless

Getting two files to play in sync is easy. Keeping them in sync for two hours is hard. The player's killer feature is its smart drift correction. Find the sync point, click "Link," and the application handles the rest, making micro-adjustments to the audio to prevent drift and ensure the commentary is as perfectly aligned in the final scene as it was in the first.

3. A Media Analysis Toolkit

This isn't just another media player; it's a utility for diving deep into your content.

• Navigate Like a Pro: Jump between chapters with dedicated buttons or by clicking markers directly on the seek bar. No more guessing where a scene begins.
• Create GIFs Instantly: Found a perfect 10-second clip for a meme or a review? Pause the video and use the built-in GIF creator to produce a high-quality.

4. Full Control Over Your Media

This tool exposes the options that matter.

• Full Track Selection: Easily switch between all available audio and subtitle tracks embedded in your video file.
• External Subtitle Support: Load a separate .srt subtitle file with one click.
• Commentary & Movie Volume Control: If the commentary track is too quiet, the dedicated volume sliders give you that extra control over the video volume and the commentary volume 

5. Save Your Work, Continue Later

Found the perfect sync offset for a 3-hour movie and its commentary? Don't lose it! The session save/load feature lets you store all file paths and the precise time offset. The next time you want to watch, just load the session file, and you're right back where you started, perfectly synced.

📖 User Guide & FAQ

Welcome to Commentary Player - Enhanced! This guide will walk you through the setup, basic workflow, and common questions.

System Requirements

Before you begin, please ensure you have the following installed:

1. Python 3: The application is built on Python.
2. Required Libraries: You can install these via pip. The main libraries are PySide6, pymediainfo, numpy, and scipy.
3. FFmpeg & FFprobe: ‼️ This is the most important requirement. ‼️ Many of the player's core features (like chapter detection and GIF creation) depend on these external tools.
   • You must download FFmpeg from the official FFmpeg website.
   • The ffmpeg and ffprobe executables must be placed in your system's PATH. This means your computer must be able to find them from any command line or terminal window. You can test this by opening a terminal and typing ffmpeg -version. If you see version information, you're all set!

How to Use: The Core Workflow

The main goal is to sync a separate audio file with a video. Here’s the typical process:

Step 1: Load Your Files 📂

• Click the 🎬 Open Video... button on the toolbar to load your main video file.
• Click the 🎧 Open Commentary... button to load your separate audio file (e.g., the commentary track).

At this point, you'll see two separate control areas: one for the video and one for the commentary. They are not yet linked.

Step 2: Find the Sync Point 🎯

Your goal is to find a moment where you can perfectly align the two tracks. A great way to do this is to find an identical audio cue in both files (like a studio logo sound, a specific line of dialogue, or an explosion).

• Use the independent play/pause and seek controls for both the video and commentary to scrub through each file.
• Play one file, pause it at the sync cue, then do the same for the other. Get them both paused at the exact same moment.

Step 3: Link the Tracks 🔗

Once you have both tracks paused at the correct starting point:

• Click the green Link Tracks button.

That's it! The player instantly calculates the time offset between the two files. The individual controls will disappear and be replaced by a set of global transport controls in the center of the bottom bar. The commentary's control panel will also be hidden for a cleaner interface.

Step 4: Play and Enjoy ▶️

Use the global play/pause button (or press the Spacebar) to start playback. Both the video and commentary will play together. The player's smart drift correction will automatically work in the background, making tiny adjustments to keep the audio perfectly locked to the video for the entire duration.

Step 5 (Optional): Save Your Session 💾

If you spent a lot of time finding the perfect sync point, you don't have to do it again!

• Click the 💾 Save Session... button on the toolbar.
• This will create a small .json file that saves the paths to your video and audio, along with the calculated time offset.
• The next time you want to watch, just use the 📂 Load Session... button, and everything will be loaded and linked for you automatically.

Frequently Asked Questions (FAQ)

❓ What file types are supported?

Thanks to the FFmpeg backend, the player supports a vast range of formats.

• Video: All common containers like .mkv, .mp4, .mov, .avi, and .webm should work without issue.
• Audio: All common formats like .mp3, .flac, .wav, .ogg, .m4a, and .aac are supported.

❓ Why isn't the chapter detection working?

This is almost always because FFmpeg and/or FFprobe are not installed correctly or are not in your system's PATH. Please see the System Requirements section above and ensure you can run ffmpeg -version from a terminal.

❓ How do I use Fullscreen or Picture-in-Picture (PiP)?

• Fullscreen: Either click the Fullscreen button in the toolbar, press Alt+Enter, or simply double-click the video. To exit, press the same keys again.
• Picture-in-Picture (PiP): Click the 🖼️ Picture-in-Picture button in the toolbar. A small, always-on-top window will appear. You can close that window to return the video to the main player.

❓ How do I create a GIF?

1. Play or seek the video to the moment you want your GIF to start.
2. Pause the video.
3. Click the 🎞️ Create GIF... button on the toolbar.
4. A dialog will ask you to confirm. It will create a 10-second GIF from that point. If you have an subtitle track active, it will crash and not make the GIF.
5. Choose where to save the file. The process will run in the background.

❓ My commentary track is too quiet! What can I do? The player gives you independent control over the volume for both the video and the commentary. You will find two separate volume sliders, allowing you to create the perfect audio mix. To make a quiet commentary easier to hear, simply lower the video's volume and raise the commentary's volume until you find a comfortable balance.

❓ How do I switch the video's audio or subtitle track?

On the toolbar, you will find a 🔊 Audio Track button and a 💬 Subtitle Track button. Clicking these will reveal a dropdown menu of all the embedded tracks found in the video file, allowing you to switch between them on the fly. You can also disable subtitles or load an external .srt file from the subtitle menu.

Keyboard Shortcuts

Key(s)	Action
Spacebar	Toggle global Play/Pause
Alt + Enter	Toggle Fullscreen
. (Period)	Frame-step forward
, (Comma)	Frame-step backward

A Note from the Developer

This project began as a personal tool to solve a specific need and was my first major foray into Python. Much of the code was developed and refined with the assistance of AI tools, including ChatGPT and Google Gemini.

I'm sharing it in the hope that it might be useful to others. Please be aware that this is a personal project released "as-is," and I am unable to offer active support or guarantee future updates.

Both the Python source code and a pre-compiled .EXE are available. You are welcome to fork the repository, modify the code, and adapt it to your own needs. If you do, please provide attribution by linking back to this project.

I hope this tool works for you as well as it does for me!