audio-extractor/README.md

Audio Extractor

A Python tool for extracting and managing audio tracks from video files using FFmpeg.

Features

• Extract Audio: Extract all audio channels from video files as individual files
• Add Tracks: Add individual audio files as new tracks to video files
• Preserve Quality: Maintains original bitrate and codec without re-encoding
• Batch Processing: Process multiple video files from a folder
• Multi-track Support: Automatically handles videos with multiple audio tracks
• Track Titles: Assign custom titles/names to audio tracks
• Flexible Output: Specify custom output folder
• Smart Matching: Automatically matches audio files to videos by base name

Installation

Prerequisites

• Python 3.6+
• FFmpeg installed and accessible in your PATH
• FFprobe (usually included with FFmpeg)

Install FFmpeg

macOS (using Homebrew):

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get install ffmpeg

Windows (using Chocolatey):

choco install ffmpeg

Or download from: https://ffmpeg.org/download.html

Usage

Extract Audio from a Single Video

python main.py extract "path/to/video.mp4" -o ./audio_output

Extract Audio from All Videos in a Folder

python main.py extract "./videos_folder" -o ./audio_output

Add Audio Tracks to Videos

# Add audio files from one folder to matching video files in another folder
python main.py add "./audio_files" -i "./videos_folder" -o ./output_videos

Add Audio with Track Titles

# Add audio tracks with a custom title (e.g., "Commentary")
python main.py add "./audio_files" -i "./videos_folder" -o ./output_videos --title "Commentary"

Legacy Command Format

The tool also supports the original command format:

python main.py --extract "target" -o output_folder

Examples

Extract from single file:

python main.py extract "movie.mp4" -o ./extracted_audio

Extract from entire folder:

python main.py extract "./my_videos" -o "./audio_tracks"

Extract with default output folder (./audio_output):

python main.py extract "video.mkv"

Add audio files to matching videos:

python main.py add "./commentary_tracks" -i "./videos" -o "./videos_with_commentary"

Add audio with custom track title:

python main.py add "./audio_files" -i "./videos" -o "./output" --title "English Commentary"

Batch add multiple audio files to the same video:

# Create audio files named like: video_name_01.aac, video_name_02.aac
# Then add them all to video_name.mp4
python main.py add "./audio_files" -i "./videos" -o "./output"

How It Works

Extraction

1. Identifies video files in the target path
2. Analyzes audio streams using ffprobe to detect codec and bitrate information
3. Extracts each audio track using FFmpeg's codec copy mode (no re-encoding)
4. Preserves quality by maintaining original bitrate and codec
5. Names files appropriately based on source video and track number

Addition

1. Identifies audio files in the audio folder
2. Matches audio to videos by comparing base names (filename without extension)
3. Adds audio as new track using FFmpeg's codec copy mode (no re-encoding)
4. Applies metadata (track title if specified via --title)
5. Handles multiple tracks by adding all matching audio files as separate tracks
6. Preserves video and maintains original quality

Output

Audio Extraction

Extracted audio files are saved with the following naming:

• Single audio track: video_name.aac (or appropriate extension)
• Multiple audio tracks: video_name_audio_0.aac, video_name_audio_1.aac, etc.

Audio Addition

When adding audio tracks:

• File Matching: Audio files are matched to videos by their base name (filename without extension)
  • Example: movie.aac matches with movie.mp4
• Multiple Tracks: If multiple audio files match a video's base name, they are added as separate audio tracks
  • Example: movie_01.aac and movie_02.aac both add to movie.mp4
• Track Titles: If --title is provided, it's applied to all added audio tracks
• Output: Modified video files are saved to the output folder with the same name as the original

Troubleshooting

"ffmpeg is not installed or not found in PATH"

• Ensure FFmpeg is installed and the ffmpeg command is accessible from your terminal
• Test with: ffmpeg -version

"No audio streams found"

• The video file may not contain any audio tracks
• Try analyzing the file with: ffprobe "video.mp4"

Extraction fails

• Check that the video file is not corrupted
• Try opening it with a media player first
• Check disk space in the output folder

Development

Project Structure

audio-extractor/
├── main.py              # Entry point and CLI argument parsing
├── audio_extractor/
│   ├── __init__.py
│   ├── cli.py          # CLI interface
│   └── extractor.py    # Core extraction logic
├── requirements.txt
└── README.md

Adding Features

To add new features:

1. Add command logic to audio_extractor/extractor.py
2. Add CLI interface to audio_extractor/cli.py
3. Add new command to the argument parser in main.py

License

MIT