tomp3 1.0.2

Convert audio files to mp3 format

tomp3

tomp3 is a command-line tool to batch convert audio files to high-quality MP3 format using FFmpeg. It supports parallel conversion, intelligent file skipping, optional deletion of originals, and customizable audio settings.

---

🚀 Features

• Batch convert .flac, .wav, and other audio files to MP3
• Input directory structure is preserved in the output (if applicable)
• Run multiple FFmpeg processes in parallel for faster conversion
• Optional deletion of original files
• Adjustable output bitrate, sample rate, quality, and channel mode (mono/stereo)
• Clean terminal UI with conversion status updates
• Dry run mode to preview which files will be converted

---

🛠 Installation

Make sure you have Python and FFmpeg installed.

Install uv if you haven't already:

pipx install uv  # (or pip)

---

📦 Usage

uv run -- python -m tomp3 <input_directory> [OPTIONS] 

Example

uv run -- python -m tomp3 ~/Music --delete --mono

This command will convert all .flac and .wav files in ~/Music to mono MP3s and delete the originals.

---

⚙️ Command-Line Arguments

Argument	FFmpeg Equivalent	Description
input	-i	Directory containing audio files to convert
--output-dir DIR	-o	Output directory for converted files. Defaults to same as input
--delete	(manual delete)	Delete original files after successful conversion
--target-extensions EXT	N/A	Comma-separated list of file extensions to convert (default: flac,wav)
--max-workers N	N/A	Number of parallel FFmpeg processes to run (default: CPUs/2)
--dry-run	N/A	Only show which files would be converted, without running FFmpeg
--mono	-ac 1	Convert audio to mono (default is stereo)
--quality N	-q:a N	LAME quality setting (0 is best, 9 is worst, default: 0)
--sample-rate SR	-ar SR	Sample rate in Hz for the output audio (default: 44100)
--bitrate BR	-b:a BR	Set constant output bitrate (e.g., 192k). Overrides quality if specified
--overwrite	-y	Overwrite existing converted files

---

🧪 Dry Run Mode

You can preview what will be converted without executing any conversions:

uv run -- python -m tomp3 <input_directory> --dry-run

---

🧼 Clean Conversion Logic

• Files are only processed if the output does not exist (unless --overwrite is used)
• Conversion progress is shown in a clean TUI
• Original files are deleted only if --delete is passed and the conversion succeeds

---

📝 License

This project is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software under the terms of the license. However, any derivative work must also be distributed under the same license.

For the full license text, see the LICENSE file or visit https://www.gnu.org/licenses/gpl-3.0.html.