TonieToolbox 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

{tonietoolbox-0.3.0.dist-info → tonietoolbox-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.3.0
+Version: 0.4.1
 Summary: Convert audio files to Tonie box compatible format
 Home-page: https://github.com/Quentendo64/TonieToolbox
 Author: Quentendo64
@@ -20,6 +20,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: protobuf<=3.19.0
+Requires-Dist: mutagen>=1.47.0
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -42,12 +43,15 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
 - [Installation](#installation)
   - [Install from PyPI (Recommended)](#install-from-pypi-recommended)
   - [Install from Source](#install-from-source)
+  - [Using Docker](#using-docker)
 - [Usage](#usage)
   - [Basic Usage](#basic-usage)
+  - [Docker Usage](#docker-usage)
   - [Advanced Options](#advanced-options)
   - [Common Usage Examples](#common-usage-examples)
   - [Media Tags](#media-tags)
   - [TeddyCloud Upload](#teddycloud-upload)
+  - [Real-World Use Cases](#real-world-use-cases)
 - [Technical Details](#technical-details)
   - [TAF File Structure](#taf-tonie-audio-format-file-structure)
   - [File Analysis](#file-analysis)
@@ -105,6 +109,32 @@ cd TonieToolbox
 pip install protobuf
 ```
 
+### Using Docker
+
+TonieToolbox is available as a Docker image, which comes with all dependencies pre-installed.
+
+#### Pull the Docker Image
+
+```
+# From Docker Hub
+docker pull quentendo64/tonietoolbox:latest
+
+# From GitHub Packages
+docker pull ghcr.io/quentendo64/tonietoolbox:latest
+```
+
+#### Build the Docker Image Locally
+
+```
+docker build -t tonietoolbox .
+```
+
+Or using docker-compose:
+
+```
+docker-compose build
+```
+
 ## Usage
 
 ### Basic Usage
@@ -161,6 +191,41 @@ By default, all generated TAF files are saved in the `.\output` directory. If yo
 tonietoolbox --recursive --output-to-source "Music/Albums"
 ```
 
+### Docker Usage
+
+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:**
+
+```bash
+# Use docker run
+docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox input/my-audio-file.mp3
+
+# Or using docker-compose
+docker-compose run --rm tonietoolbox input/my-audio-file.mp3
+```
+
+**Process folders recursively:**
+
+```bash
+# Use docker run
+docker run --rm -v "$(pwd)/input:/tonietoolbox/input" -v "$(pwd)/output:/tonietoolbox/output" quentendo64/tonietoolbox --recursive input/folder
+
+```
+
+**Advanced options with Docker:**
+
+```bash
+# Convert with custom settings
+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/folder
+```
+
+**Upload to TeddyCloud with Docker:**
+
+```bash
+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-artwork
+```
+
 ### Advanced Options
 
 Run the following command to see all available options:
@@ -175,10 +240,10 @@ usage: TonieToolbox.py [-h] [-v] [--upload URL] [--include-artwork] [--get-tags
                     [--ignore-ssl-verify] [--special-folder FOLDER] [--path PATH]
                     [--show-progress] [--connection-timeout SECONDS]
                     [--read-timeout SECONDS] [--max-retries RETRIES]
-                    [--retry-delay SECONDS] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC]
-                    [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
-                    [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
-                    [--show-tags] [-d] [-T] [-q] [-Q]
+                    [--retry-delay SECONDS] [--create-custom-json] [-t TIMESTAMP] [-f FFMPEG] 
+                    [-o OPUSENC] [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
+                    [-A] [-k] [-u] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
+                    [--show-tags] [-S] [-F] [-X] [-d] [-T] [-q] [-Q]
                     SOURCE [TARGET]
 
 Create Tonie compatible file from Ogg opus file(s).
@@ -204,6 +269,7 @@ TeddyCloud Options:
                         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
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -224,10 +290,10 @@ optional arguments:
                         Save output files in the source directory instead of output directory
   -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 (DEPRECATED)
   -C, --compare FILE2   Compare input file with another .taf file for debugging
   -D, --detailed-compare
                         Show detailed OGG page differences when comparing files
-
 Media Tag Options:
   -m, --use-media-tags  Use media tags from audio files for naming
   --name-template TEMPLATE
@@ -247,6 +313,7 @@ Logging Options:
   -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 folder
 ```
 
 ### Common Usage Examples
@@ -291,6 +358,29 @@ tonietoolbox input.mp3 --timestamp ./reference.taf  # Reference TAF for extracti
 tonietoolbox input.mp3 --bitrate 128
 ```
 
+#### Constant bitrate encoding:
+
+For 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 128
+```
+
+#### Append Tonie tag:
+
+You 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 a complex folder structure:
 
 Process an audiobook series with multiple folders:
@@ -302,7 +392,128 @@ tonietoolbox --recursive "\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 "\Hörspiele\"
+tonietoolbox --recursive --output-to-source "\Hörspiele\" 
+```
+
+#### Automatic dependency download:
+
+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"
+```
+
+#### Keep temporary files:
+
+When troubleshooting or debugging, you can keep the temporary opus files:
+
+```
+# Keep temporary opus files in the temp folder
+tonietoolbox input.mp3 --keep-temp
+
+```
+
+#### Working with list files:
+
+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.taf
+```
+
+#### TeddyCloud advanced options:
+
+Customize 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 library
+```
+
+#### Get available tags from TeddyCloud:
+
+To see which tags you can use with your TeddyCloud server:
+
+```
+tonietoolbox --get-tags https://teddycloud.example.com
+```
+
+#### Version checking and updates:
+
+TonieToolbox 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-cache
+```
+
+#### Legacy tag options:
+
+Use legacy hardcoded tags instead of dynamic TonieToolbox tags:
+
+```
+tonietoolbox input.mp3 --use-legacy-tags
+```
+
+#### Create custom JSON data:
+
+When 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-json
+```
+
+This will fetch and update the custom Tonies JSON data in the TeddyCloud server with information from your audio files.
+
+#### Logging and Troubleshooting:
+
+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 --silent
+```
+
+You 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/" --quiet
 ```
 
 ### Media Tags
@@ -410,6 +621,52 @@ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --ignore-ssl-v
 
 Use this option if the TeddyCloud server uses a self-signed certificate.
 
+## Real-World Use Cases
+
+### Converting an Audiobook Series
+
+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:
+1. Recursively process the Die Drei Fragezeichen audioplays directory
+2. Use a naming template based on source metadata
+3. Encode at 128 kbps
+4. Upload both audio files and cover art to TeddyCloud
+
+### Creating Children's Story Collections
+
+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" --debug
+```
+
+This command:
+1. Processes a list of story audio files
+2. Names the output based on metadata
+3. Uses constant bitrate encoding for consistent quality
+4. Automatically downloads dependencies if needed
+5. Shows detailed debug information during the process
+
+
+### Advanced Media Tag Usage
+
+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 as example.
+
 ## Technical Details
 
 ### TAF (Tonie Audio Format) File Structure

tonietoolbox-0.4.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+TonieToolbox/__init__.py,sha256=J5dz_xd-IvgNUuHuz0CdoFGZceDpI0_ESj_3jo_OAKo,96
+TonieToolbox/__main__.py,sha256=71HjJZFNfdflCbwuL28xHpKkwLIKAXW6sVpGX9TQRII,37202
+TonieToolbox/audio_conversion.py,sha256=nV87LTzuxeJQughu-esxTq2aZq-BvaTURj-pvBqygQs,13075
+TonieToolbox/constants.py,sha256=BQ6eUNvT3eXgsz8KFYMrqpn5vRPXrp2d6folxP6H03E,4374
+TonieToolbox/dependency_manager.py,sha256=EvVUO4T1CrhUXlrVk9HBgCRDER3b1BRNdgkZLSpCTho,27921
+TonieToolbox/filename_generator.py,sha256=RqQHyGTKakuWR01yMSnFVMU_HfLw3rqFxKhXNIHdTlg,3441
+TonieToolbox/logger.py,sha256=eZoQj4xICKEZ645GhIfZhAPAjgbgjnnfTXZ_soPjyDg,3017
+TonieToolbox/media_tags.py,sha256=PnvdHh_1RV3Fi-Wkqz5DMDjSksLsmWPrApv-6BA82jE,23206
+TonieToolbox/ogg_page.py,sha256=-ViaIRBgh5ayfwmyplL8QmmRr5P36X8W0DdHkSFUYUU,21948
+TonieToolbox/opus_packet.py,sha256=OcHXEe3I_K4mWPUD55prpG42sZxJsEeAxqSbFxBmb0c,7895
+TonieToolbox/recursive_processor.py,sha256=m70-oJ4MRXvI9OMy14sC9UsQIxwVEnEoA3hhLGdHhL4,13457
+TonieToolbox/teddycloud.py,sha256=ATfCLKecjBZRwIzhPkNcOKELRSbnmIyeQh-1imuTe9A,27281
+TonieToolbox/tonie_analysis.py,sha256=kp4Wx4cTDddtF2AlS6IX4xs1vQ-mpZ0gsAy4-UdRAAM,23287
+TonieToolbox/tonie_file.py,sha256=_LyIsUp2NmpkUVViiLY7EhXitrY4S27xKG5lvZdECJE,21031
+TonieToolbox/tonie_header.proto,sha256=WaWfwO4VrwGtscK2ujfDRKtpeBpaVPoZhI8iMmR-C0U,202
+TonieToolbox/tonie_header_pb2.py,sha256=s5bp4ULTEekgq6T61z9fDkRavyPM-3eREs20f_Pxxe8,3665
+TonieToolbox/tonies_json.py,sha256=AAYPTDTVZg4sm5AAnUKPPAifTM1iLh6Oa96ic84K2m0,20673
+TonieToolbox/version_handler.py,sha256=7Zx-pgzAUhz6jMplvNal1wHyxidodVxaNcAV0EMph5k,9778
+tonietoolbox-0.4.1.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
+tonietoolbox-0.4.1.dist-info/METADATA,sha256=qveJ2gYUaso5-UsLJevMumuiHNsbh75m13piICWknSg,24105
+tonietoolbox-0.4.1.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+tonietoolbox-0.4.1.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
+tonietoolbox-0.4.1.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
+tonietoolbox-0.4.1.dist-info/RECORD,,

tonietoolbox-0.3.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-TonieToolbox/__init__.py,sha256=1DGgQLdpAkK84simgtWndHZBKXuXCb-jPnMK_wvNOWc,96
-TonieToolbox/__main__.py,sha256=Y6-gjbjNbKhpEvV6wi8BpZSUXXezxfgZT5g8HfMeO4E,34078
-TonieToolbox/audio_conversion.py,sha256=ra72qsE8j2GEP_4kqDT9m6aKlnnREZhZAlpf7y83pA0,11202
-TonieToolbox/constants.py,sha256=QQWQpnCI65GByLlXLOkt2n8nALLu4m6BWp0zuhI3M04,2021
-TonieToolbox/dependency_manager.py,sha256=EvVUO4T1CrhUXlrVk9HBgCRDER3b1BRNdgkZLSpCTho,27921
-TonieToolbox/filename_generator.py,sha256=RqQHyGTKakuWR01yMSnFVMU_HfLw3rqFxKhXNIHdTlg,3441
-TonieToolbox/logger.py,sha256=Up9fBVkOZwkY61_645bX4tienCpyVSkap-FeTV0v730,1441
-TonieToolbox/media_tags.py,sha256=XzCuBcaqBPiSCBip8rWrJ3hTHDwEEN1flyPywM7CMsg,22250
-TonieToolbox/ogg_page.py,sha256=-ViaIRBgh5ayfwmyplL8QmmRr5P36X8W0DdHkSFUYUU,21948
-TonieToolbox/opus_packet.py,sha256=OcHXEe3I_K4mWPUD55prpG42sZxJsEeAxqSbFxBmb0c,7895
-TonieToolbox/recursive_processor.py,sha256=m70-oJ4MRXvI9OMy14sC9UsQIxwVEnEoA3hhLGdHhL4,13457
-TonieToolbox/teddycloud.py,sha256=YRgOU3f1qVDSoV05mCCDHb4pd00aI_oD8HViIotvez4,23366
-TonieToolbox/tonie_analysis.py,sha256=kp4Wx4cTDddtF2AlS6IX4xs1vQ-mpZ0gsAy4-UdRAAM,23287
-TonieToolbox/tonie_file.py,sha256=vY0s8X4ln35ZXpdpGmBcIxgpTJAjduiVvBh34WObyrw,19647
-TonieToolbox/tonie_header.proto,sha256=WaWfwO4VrwGtscK2ujfDRKtpeBpaVPoZhI8iMmR-C0U,202
-TonieToolbox/tonie_header_pb2.py,sha256=s5bp4ULTEekgq6T61z9fDkRavyPM-3eREs20f_Pxxe8,3665
-TonieToolbox/version_handler.py,sha256=7Zx-pgzAUhz6jMplvNal1wHyxidodVxaNcAV0EMph5k,9778
-tonietoolbox-0.3.0.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
-tonietoolbox-0.3.0.dist-info/METADATA,sha256=17k_CP3FXVhfO60HrS3CWP1bfN-pGNwNFwtfd9QzQj4,16695
-tonietoolbox-0.3.0.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
-tonietoolbox-0.3.0.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
-tonietoolbox-0.3.0.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
-tonietoolbox-0.3.0.dist-info/RECORD,,