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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.3.0
+Version: 0.4.0
 Summary: Convert audio files to Tonie box compatible format
 Home-page: https://github.com/Quentendo64/TonieToolbox
 Author: Quentendo64
@@ -48,6 +48,7 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
   - [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)
@@ -175,10 +176,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 +205,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 +226,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 +249,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 +294,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:
@@ -305,6 +331,127 @@ Process a music collection with nested album folders and save TAF files alongsid
 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
 
 TonieToolbox 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.
@@ -410,6 +557,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.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+TonieToolbox/__init__.py,sha256=uS1mimlbtKGNhMjaW_Sp1QgltaEgqWBllV96x2O94Lc,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.0.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
+tonietoolbox-0.4.0.dist-info/METADATA,sha256=y7uwI3Px73oalRuO88NoTVllyj3IOfLix4-wix6IAEE,22378
+tonietoolbox-0.4.0.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+tonietoolbox-0.4.0.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
+tonietoolbox-0.4.0.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
+tonietoolbox-0.4.0.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,,