# 🎵 Audio Splitter

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FFmpeg](https://img.shields.io/badge/FFmpeg-required-green.svg)](https://ffmpeg.org/)
[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docker](https://img.shields.io/badge/Docker-ready-blue.svg)](https://www.docker.com/)

**Split audio files into tracks using a flexible tracklist format.**

> A powerful command‑line tool that reads a tracklist (with timestamps) and splits an audio file into individual tracks. Supports multiple audio/video containers, metadata writing, and fully customisable input/output formats.

---

## ✨ Features

- **Flexible tracklist parsing** – Define your own format with placeholders (`%ts`, `%tn`, `%an`, `%al`, `%date`, `%ext`)
- **Timestamp support** – Handle both `start-only` (`00:00`) and `start:end` (`00:00-01:30`) timestamps
- **Multiple stream support** – Preserve audio, video, and subtitle streams (or drop them selectively)
- **Metadata writing** – Write `title`, `artist`, `album`, `date`, `track`, and `comment` to output files
- **Custom output filenames** – Define your own naming template using placeholders (`%an-%tn.%ext`)
- **Character replacement** – Replace problematic filename characters with a custom character
- **Dry‑run mode** – Preview parsed tracks without splitting
- **Skip existing files** – Avoid overwriting already‑extracted tracks
- **Delete original** – Optionally remove the input file after successful splitting
- **Docker image** – Run without installing dependencies; simple one‑line commands

---

## 📦 Installation

### Prerequisites

- **Python 3.8 or higher**
- **FFmpeg** – required for audio processing

### Install FFmpeg

| OS                   | Command                                                      |
| -------------------- | ------------------------------------------------------------ |
| **Ubuntu/Debian**    | `sudo apt install ffmpeg`                                    |
| **macOS (Homebrew)** | `brew install ffmpeg`                                        |
| **Windows**          | Download from [ffmpeg.org](https://ffmpeg.org/download.html) |

### Install Audio Splitter

Clone the repository and install:

```bash
git clone https://git.vmn.su/max/audio_splitter.git
cd audio_splitter
pip install .
```

Now the `audio_splitter` command is available globally:

```bash
audio_splitter input.mp3 tracks.txt
```

> **Tip:** For development, install in editable mode: `pip install -e .`

---

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

For bug reports or feature requests, please [open an issue](https://git.vmn.su/max/audio_splitter/issues).

---

## 📄 License

Distributed under the GNU General Public License v3 (or later). See the [LICENSE](LICENSE) file for more details.

---

## 🙏 Acknowledgements

- [FFmpeg](https://ffmpeg.org/) – the powerhouse behind audio processing
- [Python](https://www.python.org/) – the language that makes it all possible
- [gosu](https://github.com/tianon/gosu) – privilege dropping for Docker

---

## 📬 Contact

**Maintainer:** Maxim Vershinin
**Project Link:** [https://git.vmn.su/max/audio_splitter](https://git.vmn.su/max/audio_splitter)