TonieToolbox 0.2.3__tar.gz → 0.4.0__tar.gz

{tonietoolbox-0.2.3/TonieToolbox.egg-info → tonietoolbox-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.2.3
+Version: 0.4.0
 Summary: Convert audio files to Tonie box compatible format
 Home-page: https://github.com/Quentendo64/TonieToolbox
 Author: Quentendo64
@@ -47,12 +47,15 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
   - [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)
   - [File Comparison](#file-comparison)
 - [Related Projects](#related-projects)
 - [Contributing](#contributing)
+- [Legal Notice](#legal-notice)
 
 ## Overview
 
@@ -69,6 +72,8 @@ The tool provides several capabilities:
 - 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
 
 ## Requirements
 
@@ -167,10 +172,14 @@ tonietoolbox -h
 
 Output:
 ```
-usage: TonieToolbox.py [-h] [-v] [-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]
+usage: TonieToolbox.py [-h] [-v] [--upload URL] [--include-artwork] [--get-tags URL] 
+                    [--ignore-ssl-verify] [--special-folder FOLDER] [--path PATH]
+                    [--show-progress] [--connection-timeout SECONDS]
+                    [--read-timeout SECONDS] [--max-retries RETRIES]
+                    [--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).
@@ -179,6 +188,25 @@ 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
+  --show-progress       Show progress bar during file upload (default: enabled)
+  --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
+
 optional arguments:
   -h, --help            show this help message and exit
   -v, --version         show program version and exit
@@ -198,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
@@ -221,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
@@ -265,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:
@@ -279,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.
@@ -325,6 +498,111 @@ This will attempt to use the album information from the audio files for naming t
 tonietoolbox --recursive --use-media-tags --name-template "{date} - {album} ({artist})" "Music/Collection/"
 ```
 
+### TeddyCloud Upload
+
+TonieToolbox can upload files directly to a TeddyCloud server, which is an alternative to the official Tonie cloud for managing custom Tonies.
+
+#### Upload a Tonie file to TeddyCloud:
+
+```
+tonietoolbox --upload https://teddycloud.example.com my_tonie.taf
+```
+
+This will upload the specified Tonie file to the TeddyCloud server.
+
+#### Upload a newly created Tonie file:
+
+You can combine conversion and upload in a single command:
+
+```
+tonietoolbox input.mp3 --upload https://teddycloud.example.com
+```
+
+This will convert the input file to TAF format and then upload it to the TeddyCloud server.
+
+#### Upload with custom path:
+
+```
+tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --path "/custom_audio"
+The path needs to be existing in the TeddyCloud Library.
+```
+
+#### Upload with artwork:
+
+TonieToolbox can automatically find and upload cover artwork alongside your Tonie files:
+
+```
+tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --include-artwork
+```
+
+This will:
+1. Look for cover images (like "cover.jpg", "artwork.png", etc.) in the source directory
+2. If no cover image is found, attempt to extract embedded artwork from the audio files
+3. Upload the artwork to the "/custom_img" directory on the TeddyCloud server
+4. The artwork will be uploaded with the same filename as the Tonie file for easier association
+
+#### Recursive processing with uploads:
+
+```
+tonietoolbox --recursive "Music/Albums" --upload https://teddycloud.example.com --include-artwork
+```
+
+This will process all folders recursively, create TAF files, and upload both the TAF files and their cover artwork to the TeddyCloud server.
+
+#### Upload with SSL certificate verification disabled:
+
+```
+tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --ignore-ssl-verify
+```
+
+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
@@ -404,3 +682,15 @@ This project is inspired by and builds upon the work of other Tonie-related open
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Legal Notice
+
+This project is an independent, community-driven effort created for educational and personal use purposes.
+
+- tonies®, toniebox®, Hörfigur® are registered trademarks of [tonies GmbH](https://tonies.com).
+- 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.