conversion_project/QUICK_REFERENCE.md

Interactive Audio Selection - Quick Reference

Command Syntax

Enable Interactive Audio Selection

python main.py "C:\path\to\videos" --filter-audio --interactive

Other Flags (Optional)

--filter-audio --interactive --cq 28 --r 1080 --language eng --test

What User Sees

Per File Prompt (appears for each video)

================================================================================
🎵 AUDIO STREAM SELECTION
================================================================================

Stream #0: 2ch | Lang: eng | Bitrate: 128kbps

Stream #1: 6ch | Lang: eng | Bitrate: 448kbps

Stream #2: 2ch | Lang: spa | Bitrate: 128kbps

Stream #3: 2ch | Lang: comment | Bitrate: 64kbps

────────────────────────────────────────────────────────────────────────────
Enter stream numbers to keep (comma-separated, e.g.: 1,2 or just 2)
Leave blank to keep all streams
────────────────────────────────────────────────────────────────────────────
➜ Keep streams: 

User Input Examples

Input	Result
1	Keep Stream #1 (6ch English, 448kbps)
1,3	Keep Streams #1 and #3
0,1,2	Keep Streams #0, #1, and #2
(blank)	Keep all 4 streams

Expected Output

✅ Keeping 1 stream(s), removing 3 stream(s)

🎬 Running CQ encode: output.mkv
...

Features

✅ Per-File Control: Different selections for each video ✅ Clear Display: See channel count, language, bitrate for each stream ✅ Flexible Input: Comma-separated numbers, optional spaces ✅ Safe Defaults: Invalid input keeps all streams ✅ Logging: All selections recorded in conversion log ✅ Backwards Compatible: Doesn't break existing workflows

Common Scenarios

Movie with Multiple Audio Tracks

Stream #0: 2ch English (128kbps)
Stream #1: 6ch English Surround (448kbps) ← Main audio
Stream #2: 2ch Spanish (128kbps)
Stream #3: 2ch Commentary (64kbps)

Input: 1,3
Output: Keep English 5.1 + Commentary

TV Episode with Multiple Languages

Stream #0: 6ch English (384kbps)
Stream #1: 6ch Spanish (384kbps)
Stream #2: 2ch Commentary (64kbps)

Input: 0,1,2
Output: Keep all (English, Spanish, Commentary)

File with Only One Audio Track

Stream #0: 6ch English (448kbps)

Input: (blank or 0)
Output: Keep the only track

FAQ

Q: What if I provide an invalid stream number? A: The tool keeps all streams and logs a warning.

Q: Can I specify stream ranges like "0-2"? A: No, use comma-separated individual numbers: "0,1,2"

Q: Do I have to answer the prompt for every file? A: Yes, this allows different selections per file. Use automatic --filter-audio mode if you want consistent filtering across all files.

Q: What happens with invalid input like "abc" or "1.5"? A: The tool keeps all streams and logs the invalid input. Then continues to the next file.

Q: Does --interactive work alone? A: Yes! If you use --interactive without --filter-audio, filtering is automatically enabled with interactive mode.

Q: Can I combine this with --language tagging? A: Yes! Use: --filter-audio --interactive --language eng This lets you select streams AND tag them with language metadata.

Integration Points

When Called

• After audio stream detection in run_ffmpeg()
• Before codec selection and FFmpeg command building
• Only if audio_filter_config.enabled = True AND audio_filter_config.interactive = True

Stream Information Provided

• Index: Stream number in FFmpeg (0-based)
• Channels: 2ch, 6ch, etc.
• Language: eng, spa, und (undefined), etc.
• Bitrate: Detected bitrate in kbps

What Gets Removed

• All streams NOT selected by user
• Metadata and descriptors for removed streams
• No re-encoding of audio (codec decisions apply per stream)

Tips & Tricks

Keeping Only Surround Audio

Most videos have stereo + surround. To keep only 5.1/6ch:

Input: 1  (if Stream #1 is 6ch)

Keeping All Commentary

Commentary tracks are usually indexed separately:

Input: 0,2,3  (Stream #0 main + #2 and #3 commentary)

English Only

If you have multiple languages:

Input: 0,1  (Stream #0 and #1 English only)

Log Output Examples

Successful Selection

User selected 2 audio stream(s): [1, 3]
Removed 1 audio stream(s): [0, 2]

Invalid Input

User provided invalid audio selection input
Keeping all audio streams

No Selection

Keeping all audio streams

Troubleshooting

Issue: Prompt doesn't appear

• Solution: Make sure both --filter-audio AND --interactive are specified

Issue: Selection is ignored

• Solution: Check log file for errors. Verify stream indices exist.

Issue: Want automatic mode back

• Solution: Use --filter-audio alone (without --interactive)