Metadata-Version: 2.4
Name: batch_audio_extract
Version: 0.7.1
Summary: A mass treatment script for extracting part of audio files using FFMPEG
Project-URL: Homepage, https://github.com/makiwara-fr/audio_extract
Project-URL: Bug Tracker, https://github.com/makiwara-fr/audio_extract/issues
Author-email: makiwara-fr <makiwara@makiwara.com>
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: pyyaml
Requires-Dist: tk
Description-Content-Type: text/markdown

# Audio Extract

[![Testing commit](https://github.com/makiwara-fr/audio_extract/actions/workflows/makefile.yml/badge.svg?branch=main)](https://github.com/makiwara-fr/audio_extract/actions/workflows/makefile.yml)

A powerful, easy-to-use batch audio extraction tool wrapping FFmpeg. Extract specific segments of multiple audio files in one go, either via a graphical user interface (GUI) or a command line interface (CLI).

---

## Features

- **Batch Processing**: Extract excerpts from all audio files (e.g., MP3, WAV) in a directory simultaneously.
- **Dual Interfaces**: Use the intuitive Graphical User Interface (GUI) or the automation-friendly Command Line Interface (CLI).
- **Flexible Configuration**: Define settings once in a `parameters.yaml` file, or override them dynamically in the CLI.
- **Fade Effects**: Apply smooth fade-out/fade-in transitions to extracted clips.
- **FFmpeg Integration**: Auto-detects FFmpeg on your system PATH or allows specifying a custom path.

---

## Prerequisites

- **FFmpeg**: Must be installed on your system. 
  - *Download link*: [https://www.ffmpeg.org/](https://www.ffmpeg.org/)
- **Python**: Version 3.7 or newer.

---

## Installation


### From Releases (Pre-built Wheel/Executable)
Download the latest wheels or standalone executable from [Releases](https://github.com/makiwara-fr/audio_extract/releases/latest).

---

## Usage

### 🖥️ Graphical Interface (GUI) - On Linux or Mac OS

The GUI allows you to select directories, adjust start/end times, toggle fade effects, and run extractions visually.

1. **Launch the GUI** by running:
   ```bash
   audio_extract_gui
   ```
2. Choose the input folder, set your extraction duration, and click **Process**.

### 🖥️ Graphical Interface (GUI) - On Windows

1. Download and run the standalone `audio_extract.exe` directly from the [Releases](https://github.com/makiwara-fr/audio_extract/releases/latest) page.
2. Choose the input folder, set your extraction duration, and click **Process**.


### 💻 Command Line Interface (CLI)

To run the CLI, navigate to your desired directory and execute:
```bash
audio_extract
```

By default, the CLI will look for a `parameters.yaml` file in the current directory to read configuration parameters.

#### Configuration File (`parameters.yaml`)
Create a `parameters.yaml` file in your working directory to customize the default run behavior:

```yaml
input_dir: "input"
output_dir: "output"
first_second: 0
last_second: 120
input_file_extension: ["mp3", "wav"]
```

#### YAML Configuration Parameters

| Parameter | Description | Default Value |
| :--- | :--- | :--- |
| `input_dir` | The directory containing the audio files to process. | Current directory |
| `output_dir` | The directory where the extracted audio clips will be saved. | `./output/` |
| `first_second` | The start time (in seconds) for the audio extraction. | `0` |
| `last_second` | The end time (in seconds) for the audio extraction. | `60` |
| `input_file_extension` | A list of file extensions to be considered for processing. | `["mp3", "wav"]` |
| `path_ffmpeg` (optional) | The path to the FFmpeg directory/binary if it is not in your system's PATH. | *Auto-detect* |
| `debug` (optional) | Enables debug mode for verbose logging. | `False` |

#### Command-Line Arguments

All parameters from `parameters.yaml` can be overridden using arguments:

| Argument | Description | YAML Parameter |
| :--- | :--- | :--- |
| `-i`, `--input` | Input directory containing audio files | `input_dir` |
| `-o`, `--output` | Output directory for extracted clips | `output_dir` |
| `-s`, `--start` | Starting second for the audio excerpt | `first_second` |
| `-e`, `--end` | Ending second for the audio excerpt | `last_second` |
| `-f`, `--fade` | Fade duration in seconds (`0` for no fade) | `fade_d` |
| `-d`, `--debug` | Enable debug mode | `debug` |

To view the CLI help menu, run:
```bash
audio_extract --help
```

---

## Examples

- **Extract the first 30 seconds of all files** from `my_audio` and save to `my_extracts`:
  ```bash
  audio_extract --input my_audio --output my_extracts --start 0 --end 30
  ```

- **Extract from second 60 to 120** with a 3-second fade duration:
  ```bash
  audio_extract --start 60 --end 120 --fade 3
  ```

- **Run in debug mode** with a custom input directory:
  ```bash
  audio_extract --debug --input /path/to/your/audio
  ```

---

## Build from Source

For development instructions and packaging details, please refer to [build.md](docs/build.md).
