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

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

@@ -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.dist-info → tonietoolbox-0.3.0.dist-info}/RECORD

@@ -1,21 +1,23 @@
-TonieToolbox/__init__.py,sha256=UhSjPdhrXyhaT47L1QQH8FMLyK-1ddkUIQWtXr71Dcs,96
-TonieToolbox/__main__.py,sha256=eumivCJXMmlGZJLk3bC61-NwQEq3x5lElSIsmb2ZKWE,11157
+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=fBojtYnzK-jN3zOj9ntwotJhnyJfv6a-iz8zivK6L_Q,25017
+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=vhQzC05bJVRPX8laj_5lxuRD40eLsZatzwCoCavMsmY,9304
+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.2.2.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
-tonietoolbox-0.2.2.dist-info/METADATA,sha256=cm2XH96XGJR6OEL0Wc0yvldIIG0rVFZvhaBheKpuzjw,10514
-tonietoolbox-0.2.2.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-tonietoolbox-0.2.2.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
-tonietoolbox-0.2.2.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
-tonietoolbox-0.2.2.dist-info/RECORD,,
+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,,

{tonietoolbox-0.2.2.dist-info → tonietoolbox-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.1)
+Generator: setuptools (79.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any