Audio Split Helper

A Python script that generates a Bash script for splitting an audio file into segments based on specified timestamps and artist information. This is useful for creating separate audio files from a single recording, such as an full event recording with multiple performers during the timespan.

Features

• Interactive mode (-i) that auto-detects audio file timestamps and guides you through configuration
• Reads audio segment data from a CSV file
• Automatically calculates recording start time from file modification time and duration
• Uses a reference timestamp and recording start datetime to accurately label each segment
• Outputs a Bash script with ffmpeg commands to split the audio file based on the specified segments
• Includes a debug mode for detailed console output during execution

Requirements

• Python 3.10 or higher
• ffmpeg installed and accessible from the command line
• uv for dependency management

Installation

Clone the repository and navigate to the project directory:

git clone https://github.com/jkarppinen/audio-split-helper.git
cd audio-split-helper

Installing Dependencies

uv sync

Usage

Interactive Mode (Recommended)

The easiest way to use the tool is with interactive mode:

uv run python audio_split_helper.py -i

This will guide you through:

1. Selecting the audio file
2. Selecting the CSV segments file (auto-detects files in the same folder)
3. Auto-detecting timestamps from file metadata and audio duration
4. Choosing the recording start datetime
5. Setting the reference timestamp
6. Generating the script

Example session:

=== Audio Split Helper - Interactive Mode ===

Enter the path to the audio file: /path/to/recording.mp3

CSV files found in /path/to:
  [1] segments.csv
  [E] Enter custom path
Your choice [1]: 1

Detected file modification time (recording end):   2024-10-26 11:30:00
Recording duration (audio file):                   13:23:39
Calculated recording start:                        2024-10-25 22:06:21
Detected file creation time:                       2024-10-25 22:00:00

Choose the recording start datetime:
  [M] Use calculated start (from modification time - duration)
  [C] Use creation time
  [E] Enter custom datetime
Your choice [M]:

Command Line Mode

The script reads from a CSV file with the following structure (comma-separated columns):

Date,Time,Artist,Start,End
2024-10-25,22:30,MZA b2b Korai,0:00,1:26:31
2024-10-26,00:00,Histec,1:26:31,2:25:00
...

• Date: The date of the segment.
• Time: The starting time of the segment in the recording.
• Artist: The artist or track name.
• Start: The segment start time within the recording.
• End: The segment end time within the recording (optional for the last segment).

Running the Script

uv run python audio_split_helper.py <reference_timestamp> <recording_datetime> --input-file <path_to_csv> [--debug]

Positional Arguments

• <reference_timestamp>: Reference timestamp in HH:MM:SS format, indicating the specific timestamp within the recording to treat as 00:00:00 (e.g., 01:26:31).
• <recording_datetime>: Actual datetime representing the real-world time of the recording’s start, in YYYY-MM-DD HH:MM:SS format.

Optional Arguments

• --input-file: Path to the CSV file with the audio segment data.
• --debug: Enables debug mode, which outputs additional information to the console.

Example

Assuming you have a CSV file named segments.csv, you can generate the script as follows:

uv run python audio_split_helper.py 01:26:31 "2024-10-26 00:00:00" --input-file segments.csv --debug

This will output a Bash script with ffmpeg commands to split the audio based on the specified segments.

Debug Mode

Use the --debug flag to get detailed output, which is helpful for troubleshooting issues with CSV reading or timestamp calculations. The debug messages will indicate:

• When the CSV file is opened.
• Information about each row processed.
• Notifications for any malformed rows skipped.

Output

The script outputs a Bash script that you can save and run to split the audio file. Each segment is labeled with the calculated timestamp and artist name, in a format like:

ffmpeg -i "$input_file" -ss <start_time_in_seconds> -to <end_time_in_seconds> -c:a copy "<output_file>.mp3"

Example output filenames:

2024-10-25_2230_MZA-b2b-Korai.mp3
2024-10-26_0000_Histec.mp3

Tests

To run all tests, use:

uv run pytest

To run tests with coverage:

uv run pytest --cov

To run a specific test file:

uv run pytest tests/test_general.py

To run a single test function:

uv run pytest tests/test_general.py::TestScriptGeneration::test_generate_script_invalid_csv

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss any changes.