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):
```bash
brew install ffmpeg
```

**Ubuntu/Debian**:
```bash
sudo apt-get install ffmpeg
```

**Windows** (using Chocolatey):
```bash
choco install ffmpeg
```

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

## Usage

### Extract Audio from a Single Video

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

### Extract Audio from All Videos in a Folder

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

### Add Audio Tracks to Videos

```bash
# 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

```bash
# 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:

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

## Examples

**Extract from single file:**
```bash
python main.py extract "movie.mp4" -o ./extracted_audio
```

**Extract from entire folder:**
```bash
python main.py extract "./my_videos" -o "./audio_tracks"
```

**Extract with default output folder (./audio_output):**
```bash
python main.py extract "video.mkv"
```

**Add audio files to matching videos:**
```bash
python main.py add "./commentary_tracks" -i "./videos" -o "./videos_with_commentary"
```

**Add audio with custom track title:**
```bash
python main.py add "./audio_files" -i "./videos" -o "./output" --title "English Commentary"
```

**Batch add multiple audio files to the same video:**
```bash
# 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