MP3 Pipeline

A simple CLI tool to split MP3 files into smaller chunks. This tool recursively searches for MP3 files in a specified directory and its subdirectories, then splits them into chunks of a specified duration.

Features

• Recursively find all MP3 files in a directory and subdirectories
• Split MP3 files into chunks of specified duration (in minutes)
• Save split files in organized subdirectories
• Command-line interface with helpful options
• Proper error handling and validation

Installation

Install from source

1. Clone this repository:

git clone <repository-url>
cd mp3-pipeline

2. Install the package in development mode:

pip install -e .

Install dependencies

The tool requires the following Python packages:

• click - for the command-line interface
• pydub - for audio processing

Note: pydub also requires FFmpeg to be installed on your system.

FFmpeg Installation

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Windows: Download from FFmpeg official website and add to PATH.

Usage

Basic Usage

Split all MP3 files in the current directory into 5-minute chunks:

mp3-split .

Split all MP3 files in a specific directory:

mp3-split /path/to/music

Advanced Usage

Specify custom chunk duration (10 minutes):

mp3-split /path/to/music --duration 10

Use a custom output subdirectory name:

mp3-split /path/to/music --output chunks

Enable verbose output:

mp3-split /path/to/music --verbose

Combine options:

mp3-split /path/to/music -d 3 -o split_files -v

Command Line Options

• DIRECTORY: The directory to search for MP3 files (required)
• --duration, -d: Duration of each chunk in minutes (default: 5)
• --output, -o: Name of subdirectory to save split files (default: "split")
• --verbose, -v: Enable verbose output
• --help, -h: Show help message

How It Works

1. The tool recursively searches the specified directory for all files ending with .mp3
2. For each MP3 file found, it checks if the file duration exceeds the chunk duration
3. If the file is longer than the chunk duration, it splits the file into chunks
4. Each chunk is saved in a subdirectory named after the output option (default: "split")
5. Chunk files are named using the pattern: {original_name}_part{number}.mp3

Example Output Structure

If you have:

/music/
├── podcast1.mp3 (25 minutes)
└── subfolder/
    └── podcast2.mp3 (12 minutes)

After running mp3-split /music --duration 10, you'll get:

/music/
├── podcast1.mp3
├── split/
│   ├── podcast1_part001.mp3 (10 minutes)
│   ├── podcast1_part002.mp3 (10 minutes)
│   └── podcast1_part003.mp3 (5 minutes)
└── subfolder/
    ├── podcast2.mp3
    └── split/
        ├── podcast2_part001.mp3 (10 minutes)
        └── podcast2_part002.mp3 (2 minutes)

Development

Running from Source

You can run the tool directly from the source code:

python -m mp3_pipeline.cli /path/to/music

Testing

Create some test MP3 files and run the tool to verify functionality:

# Test with verbose output
mp3-split test_data --duration 2 --verbose

Requirements

• Python 3.10 or higher
• FFmpeg (required by pydub for MP3 processing)
• See pyproject.toml for Python package dependencies

License

Add your license information here.

Contributing

Add contribution guidelines here.