TonieToolbox 0.2.2__tar.gz → 0.3.0__tar.gz

{tonietoolbox-0.2.2/TonieToolbox.egg-info → tonietoolbox-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.2.2
+Version: 0.3.0
 Summary: Convert audio files to Tonie box compatible format
 Home-page: https://github.com/Quentendo64/TonieToolbox
 Author: Quentendo64
@@ -46,12 +46,15 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
   - [Basic Usage](#basic-usage)
   - [Advanced Options](#advanced-options)
   - [Common Usage Examples](#common-usage-examples)
+  - [Media Tags](#media-tags)
+  - [TeddyCloud Upload](#teddycloud-upload)
 - [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
 
@@ -67,15 +70,19 @@ The tool provides several capabilities:
 - 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
 
 ## Requirements
 
 - Python 3.6 or higher
-- FFmpeg (for converting non-opus audio files).
+- FFmpeg (for converting non-opus audio files)
 - opus-tools (specifically `opusenc` for 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.
+If the requirements are not found in PATH. TonieToolbox will download the missing requirements with --auto-download.
 
 ## Installation
 
@@ -164,9 +171,14 @@ tonietoolbox -h
 
 Output:
 ```
-usage: TonieToolbox.py [-h] [-v] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC] 
+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] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC]
                     [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
-                    [-A] [-k] [-C FILE2] [-D] [-d] [-T] [-q] [-Q]
+                    [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
+                    [--show-tags] [-d] [-T] [-q] [-Q]
                     SOURCE [TARGET]
 
 Create Tonie compatible file from Ogg opus file(s).
@@ -175,6 +187,24 @@ 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)
+
 optional arguments:
   -h, --help            show this help message and exit
   -v, --version         show program version and exit
@@ -198,6 +228,12 @@ optional arguments:
   -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
+                        Template for naming files using media tags. Example: "{album} - {artist}"
+  --show-tags           Show available media tags from input files
+
 Version Check Options:
   -S, --skip-update-check
                         Skip checking for updates
@@ -269,6 +305,111 @@ Process a music collection with nested album folders and save TAF files alongsid
 tonietoolbox --recursive --output-to-source "\Hörspiele\"
 ```
 
+### 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.
+
+#### View available tags in audio files:
+
+To see what tags are available in your audio files:
+
+```
+tonietoolbox --show-tags input.mp3
+```
+
+This will display all readable tags from the file, which can be useful for creating naming templates.
+
+#### Use media tags for file naming:
+
+To use the metadata from audio files when generating output filenames:
+
+```
+tonietoolbox input.mp3 --use-media-tags
+```
+
+For single files, this will use a default template of "{title} - {artist}" for the output filename.
+
+#### Custom naming templates:
+
+You can specify custom templates for generating filenames based on the audio metadata:
+
+```
+tonietoolbox input.mp3 --use-media-tags --name-template "{artist} - {album} - {title}"
+```
+
+#### Recursive processing with media tags:
+
+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/"
+```
+
+### 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.
+
 ## Technical Details
 
 ### TAF (Tonie Audio Format) File Structure
@@ -348,3 +489,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.

{tonietoolbox-0.2.2 → tonietoolbox-0.3.0}/README.md

@@ -19,12 +19,15 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
   - [Basic Usage](#basic-usage)
   - [Advanced Options](#advanced-options)
   - [Common Usage Examples](#common-usage-examples)
+  - [Media Tags](#media-tags)
+  - [TeddyCloud Upload](#teddycloud-upload)
 - [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
 
@@ -40,15 +43,19 @@ The tool provides several capabilities:
 - 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
 
 ## Requirements
 
 - Python 3.6 or higher
-- FFmpeg (for converting non-opus audio files).
+- FFmpeg (for converting non-opus audio files)
 - opus-tools (specifically `opusenc` for 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.
+If the requirements are not found in PATH. TonieToolbox will download the missing requirements with --auto-download.
 
 ## Installation
 
@@ -137,9 +144,14 @@ tonietoolbox -h
 
 Output:
 ```
-usage: TonieToolbox.py [-h] [-v] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC] 
+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] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC]
                     [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
-                    [-A] [-k] [-C FILE2] [-D] [-d] [-T] [-q] [-Q]
+                    [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
+                    [--show-tags] [-d] [-T] [-q] [-Q]
                     SOURCE [TARGET]
 
 Create Tonie compatible file from Ogg opus file(s).
@@ -148,6 +160,24 @@ 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)
+
 optional arguments:
   -h, --help            show this help message and exit
   -v, --version         show program version and exit
@@ -171,6 +201,12 @@ optional arguments:
   -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
+                        Template for naming files using media tags. Example: "{album} - {artist}"
+  --show-tags           Show available media tags from input files
+
 Version Check Options:
   -S, --skip-update-check
                         Skip checking for updates
@@ -242,6 +278,111 @@ Process a music collection with nested album folders and save TAF files alongsid
 tonietoolbox --recursive --output-to-source "\Hörspiele\"
 ```
 
+### 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.
+
+#### View available tags in audio files:
+
+To see what tags are available in your audio files:
+
+```
+tonietoolbox --show-tags input.mp3
+```
+
+This will display all readable tags from the file, which can be useful for creating naming templates.
+
+#### Use media tags for file naming:
+
+To use the metadata from audio files when generating output filenames:
+
+```
+tonietoolbox input.mp3 --use-media-tags
+```
+
+For single files, this will use a default template of "{title} - {artist}" for the output filename.
+
+#### Custom naming templates:
+
+You can specify custom templates for generating filenames based on the audio metadata:
+
+```
+tonietoolbox input.mp3 --use-media-tags --name-template "{artist} - {album} - {title}"
+```
+
+#### Recursive processing with media tags:
+
+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/"
+```
+
+### 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.
+
 ## Technical Details
 
 ### TAF (Tonie Audio Format) File Structure
@@ -320,4 +461,16 @@ 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.
+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.

{tonietoolbox-0.2.2 → tonietoolbox-0.3.0}/TonieToolbox/__init__.py

@@ -2,4 +2,4 @@
 TonieToolbox - Convert audio files to Tonie box compatible format
 """
 
-__version__ = '0.2.2'
+__version__ = '0.3.0'