A Toolkit for converting various audio formats into the Tonie-compatible TAF format (Tonie Audio Format) and interacting with TeddyCloud powered by RevvoX
→ HOWTO Guide for Beginners
→ Contributing Guidelines
The latest release of TonieToolbox includes exciting new capabilities:
- Enhanced Media Tag Support: Better handling of complex audio libraries with advanced metadata extraction and usage of tags in your upload path (--path) or as output directory with the new argument --output-to-template eg. "C:\Music\{albumartist}\{album}"
- Windows Context Menu Integration: Right-click to convert audio files directly from File Explorer. Use --config-integration to configure the upload functions. If not needed just use --install-integration
- Overview
- Features
- Requirements
- Installation
- Usage
- Technical Details
- Related Projects
- Contributing
- Legal Notice
- Support
TonieToolbox allows you to create custom audio content for Tonie boxes by converting various audio formats into the specific file format required by Tonie devices.
The tool provides several capabilities:
- Convert single or multiple audio files into a Tonie-compatible format
- Process complex folder structures recursively to handle entire audio collections
- Analyze and validate existing Tonie files
- Split Tonie files into individual opus tracks
- Compare two TAF files for debugging differences
- Support various input formats through FFmpeg conversion
- Extract and use audio media tags (ID3, Vorbis Comments, etc.) for better file naming
- Upload Tonie files directly to a TeddyCloud server
- Automatically upload cover artwork alongside Tonie files
- Python 3.6 or higher
- FFmpeg (for converting non-opus audio files)
- opus-tools (specifically
opusencfor encoding to opus format) - mutagen (for reading audio file metadata, auto-installed when needed)
Make sure FFmpeg and opus-tools are installed on your system and accessible in your PATH.
If the requirements are not found in PATH, TonieToolbox will download the missing requirements with --auto-download.
pip install tonietoolboxThis will install TonieToolbox and its dependencies, making the tonietoolbox command available in your terminal.
# Clone the repository
git clone https://github.com/Quentendo64/TonieToolbox.git
cd TonieToolbox
# Install dependencies
pip install protobufTonieToolbox is available as a Docker image, which comes with all dependencies pre-installed.
# From Docker Hub
docker pull quentendo64/tonietoolbox:latest
# From GitHub Packages
docker pull ghcr.io/quentendo64/tonietoolbox:latestdocker build -t tonietoolbox .Or using docker-compose:
docker-compose buildConvert a single audio file to Tonie format:
If installed via pip:
tonietoolbox input.mp3If installed from source:
python TonieToolbox.py input.mp3This will create a file named input.taf in the .\output directory.
Specify output filename:
tonietoolbox input.mp3 my_tonie.tafThis will create a file named my_tonie.taf in the .\output directory.
Convert multiple files:
You can specify a directory to convert all audio files within it:
tonietoolbox input_directory/Or use a list file (.lst) containing paths to multiple audio files:
tonietoolbox playlist.lstProcess folders recursively:
To process an entire folder structure with multiple audio folders:
tonietoolbox --recursive "Music/Albums"This will scan all subfolders, identify those containing audio files, and create a TAF file for each folder.
By default, all generated TAF files are saved in the .\output directory. If you want to save each TAF file in its source directory instead:
tonietoolbox --recursive --output-to-source "Music/Albums"Using TonieToolbox with Docker simplifies the setup process as all dependencies (FFmpeg and opus-tools) are pre-installed.
Convert a single audio file to Tonie format:
On Windows PowerShell/Unix/macOS:
docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox input/my-audio-file.mp3On Windows (CMD):
docker run --rm -v "%cd%\input:/tonietoolbox/input" -v "%cd%\output:/tonietoolbox/output" quentendo64/tonietoolbox input/my-audio-file.mp3Or using docker-compose:
docker-compose run --rm tonietoolbox input/my-audio-file.mp3Process folders recursively:
docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox --recursive input/folderAdvanced options with Docker:
docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox --recursive --use-media-tags --name-template "{album} - {artist}" --bitrate 128 input/folderUpload to TeddyCloud with Docker:
docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox input/my-audio-file.mp3 --upload https://teddycloud.example.com --include-artworkRun the following command to see all available options:
tonietoolbox -hOutput:
usage: TonieToolbox.py [-h] [-v] [--upload URL] [--include-artwork] [--get-tags URL]
[--ignore-ssl-verify] [--special-folder FOLDER] [--path PATH]
[--connection-timeout SECONDS] [--read-timeout SECONDS]
[--max-retries RETRIES] [--retry-delay SECONDS]
[--create-custom-json] [--version-2] [--username USERNAME]
[--password PASSWORD] [--client-cert CERT_FILE]
[--client-key KEY_FILE] [-t TIMESTAMP] [-f FFMPEG]
[-o OPUSENC] [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
[-fc] [--no-mono-conversion] [-A] [-k] [-u] [-C FILE2] [-D]
[--config-integration] [--install-integration]
[--uninstall-integration] [-m] [--name-template TEMPLATE]
[--output-to-template PATH_TEMPLATE] [--show-tags]
[-S] [-F] [-X] [-d] [-T] [-q] [-Q] [--log-file]
SOURCE [TARGET]
Create Tonie compatible file from Ogg opus file(s).
positional arguments:
SOURCE input file or directory or a file list (.lst)
TARGET the output file name (default: ---ID---)
TeddyCloud Options:
--upload URL Upload to TeddyCloud instance (e.g., https://teddycloud.example.com). Supports .taf, .jpg, .jpeg, .png files.
--include-artwork Upload cover artwork image alongside the Tonie file when using --upload
--get-tags URL Get available tags from TeddyCloud instance
--ignore-ssl-verify Ignore SSL certificate verification (for self-signed certificates)
--special-folder FOLDER
Special folder to upload to (currently only "library" is supported)
--path PATH Path where to write the file on TeddyCloud server (supports templates like "/{albumartist}/{album}")
--connection-timeout SECONDS
Connection timeout in seconds (default: 10)
--read-timeout SECONDS
Read timeout in seconds (default: 300)
--max-retries RETRIES
Maximum number of retry attempts (default: 3)
--retry-delay SECONDS
Delay between retry attempts in seconds (default: 5)
--create-custom-json Fetch and update custom Tonies JSON data
--version-2 Use version 2 of the Tonies JSON format (default: version 1)
--username USERNAME Username for basic authentication
--password PASSWORD Password for basic authentication
--client-cert CERT_FILE
Path to client certificate file for certificate-based authentication
--client-key KEY_FILE
Path to client private key file for certificate-based authentication
optional arguments:
-h, --help show this help message and exit
-v, --version show program version and exit
-t, --timestamp TIMESTAMP
set custom timestamp / bitstream serial
-f, --ffmpeg FFMPEG specify location of ffmpeg
-o, --opusenc OPUSENC specify location of opusenc
-b, --bitrate BITRATE set encoding bitrate in kbps (default: 96)
-c, --cbr encode in cbr mode
-a, --append-tonie-tag TAG
append [TAG] to filename (must be an 8-character hex value)
-n, --no-tonie-header do not write Tonie header
-i, --info Check and display info about Tonie file
-s, --split Split Tonie file into opus tracks
-r, --recursive Process folders recursively
-O, --output-to-source
Save output files in the source directory instead of output directory
-fc, --force-creation
Force creation of Tonie file even if it already exists
--no-mono-conversion Do not convert mono audio to stereo (default: convert mono to stereo)
-A, --auto-download Automatically download FFmpeg and opusenc if needed
-k, --keep-temp Keep temporary opus files in a temp folder for testing
-u, --use-legacy-tags Use legacy hardcoded tags instead of dynamic TonieToolbox tags
-C, --compare FILE2 Compare input file with another .taf file for debugging
-D, --detailed-compare
Show detailed OGG page differences when comparing files
--config-integration Configure context menu integration
--install-integration
Integrate with the system (e.g., create context menu entries)
--uninstall-integration
Uninstall context menu integration
Media Tag Options:
-m, --use-media-tags Use media tags from audio files for naming
--name-template TEMPLATE
Template for naming files using media tags. Example: "{album} - {artist}"
--output-to-template PATH_TEMPLATE
Template for output path using media tags. Example: "C:\Music\{albumartist}\{album}"
--show-tags Show available media tags from input files
Version Check Options:
-S, --skip-update-check
Skip checking for updates
-F, --force-refresh-cache
Force refresh of update information from PyPI
-X, --clear-version-cache
Clear cached version information
Logging Options:
-d, --debug Enable debug logging
-T, --trace Enable trace logging (very verbose)
-q, --quiet Show only warnings and errors
-Q, --silent Show only errors
--log-file Save logs to a timestamped file in .tonietoolbox foldertonietoolbox --info my_tonie.taftonietoolbox --split my_tonie.taf Compare two TAF files for debugging purposes:
tonietoolbox file1.taf --compare file2.tafFor detailed comparison including OGG page differences:
tonietoolbox file1.taf --compare file2.taf --detailed-comparetonietoolbox input.mp3 --timestamp 1745078762 # UNIX Timestamp
tonietoolbox input.mp3 --timestamp 0x6803C9EA # Bitstream time
tonietoolbox input.mp3 --timestamp ./reference.taf # Reference TAF for extractiontonietoolbox input.mp3 --bitrate 128For more predictable file sizes and consistent quality, use constant bitrate (CBR) encoding:
# Encode with constant bitrate at 96 kbps (default)
tonietoolbox input.mp3 --cbr
# Encode with constant bitrate at 128 kbps
tonietoolbox input.mp3 --cbr --bitrate 128You can append a hexadecimal tag to the filename, which is useful for organizing Tonie files:
# Add an 8-character hex tag to filename
tonietoolbox input.mp3 --append-tonie-tag 7F8A6B2E
# The output will be named "input-7F8A6B2E.taf"Process an audiobook series with multiple folders:
tonietoolbox --recursive "C:\Hörspiele\Die drei Fragezeichen\Folgen"Process a music collection with nested album folders and save TAF files alongside the source directories:
tonietoolbox --recursive --output-to-source "C:\Hörspiele\" If FFmpeg or opusenc are not found in your PATH, TonieToolbox can automatically download them:
# Automatically download dependencies when needed
tonietoolbox input.mp3 --auto-download
# Specify custom FFmpeg or opusenc locations
tonietoolbox input.mp3 --ffmpeg "C:\path\to\ffmpeg.exe" --opusenc "C:\path\to\opusenc.exe"When troubleshooting or debugging, you can keep the temporary opus files:
# Keep temporary opus files in the temp folder
tonietoolbox input.mp3 --keep-temp
Create a text file (.lst) with paths to audio files for batch processing:
# Contents of playlist.lst:
C:\Music\song1.mp3
"C:\Music\song2.flac"
C:\Music\song3.wav
"C:\Music Path With Spaces\song2.flac"
# Process the list file
tonietoolbox playlist.lst my_playlist.tafCustomize your TeddyCloud uploads with connection options:
# Upload with custom timeouts and retry parameters
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --connection-timeout 20 --read-timeout 600 --max-retries 5 --retry-delay 10
# Disable progress bar during upload
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --show-progress=False
# Upload to a special folder in TeddyCloud
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --special-folder libraryTo see which tags you can use with your TeddyCloud server:
tonietoolbox --get-tags https://teddycloud.example.comTonieToolbox can check for newer versions and notify you when there are updates available:
# Skip checking for updates if you're offline or want faster startup
tonietoolbox input.mp3 --skip-update-check
# Force refresh of version information from PyPI
tonietoolbox input.mp3 --force-refresh-cache
# Clear cached version information
tonietoolbox --clear-version-cacheUse legacy hardcoded tags instead of dynamic TonieToolbox tags:
tonietoolbox input.mp3 --use-legacy-tagsWhen uploading to TeddyCloud, you can also update the custom Tonies JSON data with information about the uploaded file:
tonietoolbox input.mp3 --upload https://teddycloud.example.com --create-custom-jsonThis will fetch and update the custom Tonies JSON data in the TeddyCloud server with information from your audio files.
Control the verbosity of console output with different logging levels:
# Enable detailed debug information (useful for troubleshooting)
tonietoolbox input.mp3 --debug
# Enable extremely verbose trace logging (developer level)
tonietoolbox input.mp3 --trace
# Reduce output to show only warnings and errors
tonietoolbox input.mp3 --quiet
# Show only critical errors (minimal output)
tonietoolbox input.mp3 --silentYou can combine logging options with other commands:
# Debug mode while splitting a TAF file
tonietoolbox --split my_tonie.taf --debug
# Quiet mode while batch processing
tonietoolbox --recursive "Music/Collection/" --quietIf a valid TAF file already exists, TonieToolbox will skip recreating it by default. To force creation even if the file exists:
# Force creation of a TAF file even if it already exists
tonietoolbox input.mp3 --force-creationThis is useful when you want to update the content or encoding settings of an existing TAF file.
TonieToolbox can integrate with Windows Explorer, allowing you to right-click on audio files or folders to convert them:
# Install context menu integration (one-time setup)
tonietoolbox --install-integration
# Configure context menu options
tonietoolbox --config-integration
# Remove context menu integration
tonietoolbox --uninstall-integrationAfter installation, you can right-click on any audio file or folder in Windows Explorer and select "Convert to Tonie Format".
When changing the configuration via --config-integration. Apply them to the integration by simply execute tonietoolbox --install-integration again.
Save detailed logs to a timestamped file for troubleshooting complex operations:
# Enable log file generation
tonietoolbox input.mp3 --log-file
# Combine with debug logging for maximum detail
tonietoolbox --recursive input_directory/ --log-file --debugLog files are saved in the .tonietoolbox\logs folder in your user directory.
Create custom directory structures based on media tags:
# Create output based on a path template
tonietoolbox input.mp3 --use-media-tags --output-to-template "C:\Music\{albumartist}\{album}"
# Use with recursive processing
tonietoolbox --recursive "Music/Collection/" --use-media-tags --output-to-template "Organized/{genre}/{year} - {album}"This creates a directory structure based on the audio files' metadata and places the converted TAF files accordingly.
Note: Authentication is based on the Features available when using TeddyCloudStarter.
TonieToolbox supports multiple authentication methods for secure TeddyCloud connections:
# Basic authentication with username and password
tonietoolbox input.mp3 --upload https://teddycloud.example.com --username admin --password secret
# Certificate-based authentication
tonietoolbox input.mp3 --upload https://teddycloud.example.com --client-cert certificate.crt --client-key private.keyChoose between different versions of the Tonies JSON format:
# Use version 2 of the Tonies JSON format (enhanced metadata)
tonietoolbox input.mp3 --upload https://teddycloud.example.com --create-custom-json --version-2TonieToolbox can read metadata tags from audio files (such as ID3 tags in MP3 files, Vorbis comments in FLAC/OGG files, etc.) and use them to create more meaningful filenames or display information about your audio collection.
To see what tags are available in your audio files:
tonietoolbox --show-tags input.mp3This will display all readable tags from the file, which can be useful for creating naming templates.
To use the metadata from audio files when generating output filenames:
tonietoolbox input.mp3 --use-media-tagsFor single files, this will use a default template of "{title} - {artist}" for the output filename.
You can specify custom templates for generating filenames based on the audio metadata:
tonietoolbox input.mp3 --use-media-tags --name-template "{artist} - {album} - {title}"When processing folders recursively, media tags can provide more consistent naming:
tonietoolbox --recursive --use-media-tags "Music/Collection/"This will attempt to use the album information from the audio files for naming the output files:
tonietoolbox --recursive --use-media-tags --name-template "{date} - {album} ({artist})" "Music/Collection/"TonieToolbox can upload files directly to a TeddyCloud server, which is an alternative to the official Tonie cloud for managing custom Tonies.
tonietoolbox --upload https://teddycloud.example.com my_tonie.tafThis will upload the specified Tonie file to the TeddyCloud server.
You can combine conversion and upload in a single command:
tonietoolbox input.mp3 --upload https://teddycloud.example.comThis will convert the input file to TAF format and then upload it to the TeddyCloud server.
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --path "/custom_audio"
# The path must already exist in the TeddyCloud Library.Note: This function will only work if the
/custom_imgfolder is mounted in the TeddyCloud Library. For an easy start and to handle this automatically (and much more), use TeddyCloudStarter.
TonieToolbox can automatically find and upload cover artwork alongside your Tonie files:
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --include-artworkThis will:
- Look for cover images (like "cover.jpg", "artwork.png", etc.) in the source directory
- If no cover image is found, attempt to extract embedded artwork from the audio files
- Upload the artwork to the "/custom_img" directory on the TeddyCloud server
- The artwork will be uploaded with the same filename as the Tonie file for easier association
tonietoolbox --recursive "Music/Albums" --upload https://teddycloud.example.com --include-artworkThis will process all folders recursively, create TAF files, and upload both the TAF files and their cover artwork to the TeddyCloud server.
tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --ignore-ssl-verifyUse this option if the TeddyCloud server uses a self-signed certificate.
To convert an entire audiobook series with proper metadata and upload to TeddyCloud:
tonietoolbox --recursive --use-media-tags --name-template "{year} - {albumartist} - {album}" --bitrate 128 --upload https://teddycloud.example.com --include-artwork "C:\Hörspiele\Die Drei Fragezeichen"This command will:
- Recursively process the Die Drei Fragezeichen audioplays directory
- Use a naming template based on source metadata
- Encode at 128 kbps
- Upload both audio files and cover art to TeddyCloud
For a custom children's story collection with chapters:
tonietoolbox story_collection.lst kids_stories.taf --bitrate 96 --cbr --auto-download --use-media-tags --name-template "{title} Stories" --debugThis command:
- Processes a list of story audio files
- Names the output based on metadata
- Uses constant bitrate encoding for consistent quality
- Automatically downloads dependencies if needed
- Shows detailed debug information during the process
For complex media tag processing:
# First check available tags
tonietoolbox --show-tags "C:\Music\Classical\Bach"
# Then use a sophisticated naming template
tonietoolbox "C:\Music\Classical\Bach" --use-media-tags --name-template "{composer} - {opus} in {key} ({conductor}, {orchestra})"The first command shows what tags are available, allowing you to create precise naming templates for classical music collections.
This project is inspired by and builds upon the work of other Tonie-related open source projects:
- opus2tonie - A command line utility to convert opus files to the Tonie audio format
- teddycloud - Self-hosted alternative to the Tonie cloud / Boxine cloud for managing custom content
- TeddyCloudStarter - A Wizard for Docker-based deployment of teddycloud
This project is an independent, community-driven effort created for educational and personal use purposes.
- tonies®, toniebox®, and Hörfigur® are registered trademarks of tonies GmbH.
- This project is not affiliated with, endorsed by, or connected to tonies GmbH in any way.
- TonieToolbox is provided "as is" without warranty of any kind, either express or implied.
- Users are responsible for ensuring their usage complies with all applicable copyright and intellectual property laws.
- This tool is intended for personal use with legally owned content only.
By using TonieToolbox, you acknowledge that the authors of this software take no responsibility for any potential misuse or any damages that might result from the use of this software.
If you need help, have questions, or want to report a bug, please use the following channels:
- GitHub Issues for bug reports and feature requests
- GitHub Discussions for general questions and community support
- HOWTO Guide for common usage instructions