TonieToolbox 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. {tonietoolbox-0.3.0/TonieToolbox.egg-info → tonietoolbox-0.4.0}/PKG-INFO +199 -6
  2. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/README.md +198 -5
  3. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/__init__.py +1 -1
  4. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/__main__.py +64 -2
  5. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/audio_conversion.py +36 -14
  6. tonietoolbox-0.4.0/TonieToolbox/constants.py +90 -0
  7. tonietoolbox-0.4.0/TonieToolbox/logger.py +103 -0
  8. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/media_tags.py +22 -6
  9. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/teddycloud.py +101 -2
  10. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_file.py +32 -12
  11. tonietoolbox-0.4.0/TonieToolbox/tonies_json.py +502 -0
  12. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0/TonieToolbox.egg-info}/PKG-INFO +199 -6
  13. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/SOURCES.txt +1 -0
  14. tonietoolbox-0.3.0/TonieToolbox/constants.py +0 -15
  15. tonietoolbox-0.3.0/TonieToolbox/logger.py +0 -57
  16. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/LICENSE.md +0 -0
  17. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/MANIFEST.in +0 -0
  18. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/dependency_manager.py +0 -0
  19. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/filename_generator.py +0 -0
  20. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/ogg_page.py +0 -0
  21. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/opus_packet.py +0 -0
  22. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/recursive_processor.py +0 -0
  23. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_analysis.py +0 -0
  24. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_header.proto +0 -0
  25. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_header_pb2.py +0 -0
  26. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/version_handler.py +0 -0
  27. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/dependency_links.txt +0 -0
  28. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/entry_points.txt +0 -0
  29. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/requires.txt +0 -0
  30. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/top_level.txt +0 -0
  31. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/pyproject.toml +0 -0
  32. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/setup.cfg +0 -0
  33. {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/setup.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: TonieToolbox
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Convert audio files to Tonie box compatible format
5
5
  Home-page: https://github.com/Quentendo64/TonieToolbox
6
6
  Author: Quentendo64
@@ -48,6 +48,7 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
48
48
  - [Common Usage Examples](#common-usage-examples)
49
49
  - [Media Tags](#media-tags)
50
50
  - [TeddyCloud Upload](#teddycloud-upload)
51
+ - [Real-World Use Cases](#real-world-use-cases)
51
52
  - [Technical Details](#technical-details)
52
53
  - [TAF File Structure](#taf-tonie-audio-format-file-structure)
53
54
  - [File Analysis](#file-analysis)
@@ -175,10 +176,10 @@ usage: TonieToolbox.py [-h] [-v] [--upload URL] [--include-artwork] [--get-tags
175
176
  [--ignore-ssl-verify] [--special-folder FOLDER] [--path PATH]
176
177
  [--show-progress] [--connection-timeout SECONDS]
177
178
  [--read-timeout SECONDS] [--max-retries RETRIES]
178
- [--retry-delay SECONDS] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC]
179
- [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
180
- [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
181
- [--show-tags] [-d] [-T] [-q] [-Q]
179
+ [--retry-delay SECONDS] [--create-custom-json] [-t TIMESTAMP] [-f FFMPEG]
180
+ [-o OPUSENC] [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
181
+ [-A] [-k] [-u] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
182
+ [--show-tags] [-S] [-F] [-X] [-d] [-T] [-q] [-Q]
182
183
  SOURCE [TARGET]
183
184
 
184
185
  Create Tonie compatible file from Ogg opus file(s).
@@ -204,6 +205,7 @@ TeddyCloud Options:
204
205
  Maximum number of retry attempts (default: 3)
205
206
  --retry-delay SECONDS
206
207
  Delay between retry attempts in seconds (default: 5)
208
+ --create-custom-json Fetch and update custom Tonies JSON data
207
209
 
208
210
  optional arguments:
209
211
  -h, --help show this help message and exit
@@ -224,10 +226,10 @@ optional arguments:
224
226
  Save output files in the source directory instead of output directory
225
227
  -A, --auto-download Automatically download FFmpeg and opusenc if needed
226
228
  -k, --keep-temp Keep temporary opus files in a temp folder for testing
229
+ -u, --use-legacy-tags Use legacy hardcoded tags instead of dynamic TonieToolbox tags (DEPRECATED)
227
230
  -C, --compare FILE2 Compare input file with another .taf file for debugging
228
231
  -D, --detailed-compare
229
232
  Show detailed OGG page differences when comparing files
230
-
231
233
  Media Tag Options:
232
234
  -m, --use-media-tags Use media tags from audio files for naming
233
235
  --name-template TEMPLATE
@@ -247,6 +249,7 @@ Logging Options:
247
249
  -T, --trace Enable trace logging (very verbose)
248
250
  -q, --quiet Show only warnings and errors
249
251
  -Q, --silent Show only errors
252
+ --log-file Save logs to a timestamped file in .tonietoolbox folder
250
253
  ```
251
254
 
252
255
  ### Common Usage Examples
@@ -291,6 +294,29 @@ tonietoolbox input.mp3 --timestamp ./reference.taf # Reference TAF for extracti
291
294
  tonietoolbox input.mp3 --bitrate 128
292
295
  ```
293
296
 
297
+ #### Constant bitrate encoding:
298
+
299
+ For more predictable file sizes and consistent quality, use constant bitrate (CBR) encoding:
300
+
301
+ ```
302
+ # Encode with constant bitrate at 96 kbps (default)
303
+ tonietoolbox input.mp3 --cbr
304
+
305
+ # Encode with constant bitrate at 128 kbps
306
+ tonietoolbox input.mp3 --cbr --bitrate 128
307
+ ```
308
+
309
+ #### Append Tonie tag:
310
+
311
+ You can append a hexadecimal tag to the filename, which is useful for organizing Tonie files:
312
+
313
+ ```
314
+ # Add an 8-character hex tag to filename
315
+ tonietoolbox input.mp3 --append-tonie-tag 7F8A6B2E
316
+
317
+ # The output will be named "input-7F8A6B2E.taf"
318
+ ```
319
+
294
320
  #### Process a complex folder structure:
295
321
 
296
322
  Process an audiobook series with multiple folders:
@@ -305,6 +331,127 @@ Process a music collection with nested album folders and save TAF files alongsid
305
331
  tonietoolbox --recursive --output-to-source "\Hörspiele\"
306
332
  ```
307
333
 
334
+ #### Automatic dependency download:
335
+
336
+ If FFmpeg or opusenc are not found in your PATH, TonieToolbox can automatically download them:
337
+
338
+ ```
339
+ # Automatically download dependencies when needed
340
+ tonietoolbox input.mp3 --auto-download
341
+
342
+ # Specify custom FFmpeg or opusenc locations
343
+ tonietoolbox input.mp3 --ffmpeg "C:\path\to\ffmpeg.exe" --opusenc "C:\path\to\opusenc.exe"
344
+ ```
345
+
346
+ #### Keep temporary files:
347
+
348
+ When troubleshooting or debugging, you can keep the temporary opus files:
349
+
350
+ ```
351
+ # Keep temporary opus files in the temp folder
352
+ tonietoolbox input.mp3 --keep-temp
353
+
354
+ ```
355
+
356
+ #### Working with list files:
357
+
358
+ Create a text file (.lst) with paths to audio files for batch processing:
359
+
360
+ ```
361
+ # Contents of playlist.lst:
362
+ C:\Music\song1.mp3
363
+ "C:\Music\song2.flac"
364
+ C:\Music\song3.wav
365
+ "C:\Music Path With Spaces\song2.flac"
366
+
367
+ # Process the list file
368
+ tonietoolbox playlist.lst my_playlist.taf
369
+ ```
370
+
371
+ #### TeddyCloud advanced options:
372
+
373
+ Customize your TeddyCloud uploads with connection options:
374
+
375
+ ```
376
+ # Upload with custom timeouts and retry parameters
377
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --connection-timeout 20 --read-timeout 600 --max-retries 5 --retry-delay 10
378
+
379
+ # Disable progress bar during upload
380
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --show-progress=False
381
+
382
+ # Upload to a special folder in TeddyCloud
383
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --special-folder library
384
+ ```
385
+
386
+ #### Get available tags from TeddyCloud:
387
+
388
+ To see which tags you can use with your TeddyCloud server:
389
+
390
+ ```
391
+ tonietoolbox --get-tags https://teddycloud.example.com
392
+ ```
393
+
394
+ #### Version checking and updates:
395
+
396
+ TonieToolbox can check for newer versions and notify you when there are updates available:
397
+
398
+ ```
399
+ # Skip checking for updates if you're offline or want faster startup
400
+ tonietoolbox input.mp3 --skip-update-check
401
+
402
+ # Force refresh of version information from PyPI
403
+ tonietoolbox input.mp3 --force-refresh-cache
404
+
405
+ # Clear cached version information
406
+ tonietoolbox --clear-version-cache
407
+ ```
408
+
409
+ #### Legacy tag options:
410
+
411
+ Use legacy hardcoded tags instead of dynamic TonieToolbox tags:
412
+
413
+ ```
414
+ tonietoolbox input.mp3 --use-legacy-tags
415
+ ```
416
+
417
+ #### Create custom JSON data:
418
+
419
+ When uploading to TeddyCloud, you can also update the custom Tonies JSON data with information about the uploaded file:
420
+
421
+ ```
422
+ tonietoolbox input.mp3 --upload https://teddycloud.example.com --create-custom-json
423
+ ```
424
+
425
+ This will fetch and update the custom Tonies JSON data in the TeddyCloud server with information from your audio files.
426
+
427
+ #### Logging and Troubleshooting:
428
+
429
+ Control the verbosity of console output with different logging levels:
430
+
431
+ ```
432
+ # Enable detailed debug information (useful for troubleshooting)
433
+ tonietoolbox input.mp3 --debug
434
+
435
+ # Enable extremely verbose trace logging (developer level)
436
+ tonietoolbox input.mp3 --trace
437
+
438
+ # Reduce output to show only warnings and errors
439
+ tonietoolbox input.mp3 --quiet
440
+
441
+ # Show only critical errors (minimal output)
442
+ tonietoolbox input.mp3 --silent
443
+ ```
444
+
445
+ You can combine logging options with other commands:
446
+
447
+ ```
448
+ # Debug mode while splitting a TAF file
449
+ tonietoolbox --split my_tonie.taf --debug
450
+
451
+ # Quiet mode while batch processing
452
+ tonietoolbox --recursive "Music/Collection/" --quiet
453
+ ```
454
+
308
455
  ### Media Tags
309
456
 
310
457
  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
410
557
 
411
558
  Use this option if the TeddyCloud server uses a self-signed certificate.
412
559
 
560
+ ## Real-World Use Cases
561
+
562
+ ### Converting an Audiobook Series
563
+
564
+ To convert an entire audiobook series with proper metadata and upload to TeddyCloud:
565
+
566
+ ```
567
+ 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"
568
+ ```
569
+
570
+ This command will:
571
+ 1. Recursively process the Die Drei Fragezeichen audioplays directory
572
+ 2. Use a naming template based on source metadata
573
+ 3. Encode at 128 kbps
574
+ 4. Upload both audio files and cover art to TeddyCloud
575
+
576
+ ### Creating Children's Story Collections
577
+
578
+ For a custom children's story collection with chapters:
579
+
580
+ ```
581
+ tonietoolbox story_collection.lst kids_stories.taf --bitrate 96 --cbr --auto-download --use-media-tags --name-template "{title} Stories" --debug
582
+ ```
583
+
584
+ This command:
585
+ 1. Processes a list of story audio files
586
+ 2. Names the output based on metadata
587
+ 3. Uses constant bitrate encoding for consistent quality
588
+ 4. Automatically downloads dependencies if needed
589
+ 5. Shows detailed debug information during the process
590
+
591
+
592
+ ### Advanced Media Tag Usage
593
+
594
+ For complex media tag processing:
595
+
596
+ ```
597
+ # First check available tags
598
+ tonietoolbox --show-tags "C:\Music\Classical\Bach"
599
+
600
+ # Then use a sophisticated naming template
601
+ tonietoolbox "C:\Music\Classical\Bach" --use-media-tags --name-template "{composer} - {opus} in {key} ({conductor}, {orchestra})"
602
+ ```
603
+
604
+ The first command shows what tags are available, allowing you to create precise naming templates for classical music collections as example.
605
+
413
606
  ## Technical Details
414
607
 
415
608
  ### TAF (Tonie Audio Format) File Structure
@@ -21,6 +21,7 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
21
21
  - [Common Usage Examples](#common-usage-examples)
22
22
  - [Media Tags](#media-tags)
23
23
  - [TeddyCloud Upload](#teddycloud-upload)
24
+ - [Real-World Use Cases](#real-world-use-cases)
24
25
  - [Technical Details](#technical-details)
25
26
  - [TAF File Structure](#taf-tonie-audio-format-file-structure)
26
27
  - [File Analysis](#file-analysis)
@@ -148,10 +149,10 @@ usage: TonieToolbox.py [-h] [-v] [--upload URL] [--include-artwork] [--get-tags
148
149
  [--ignore-ssl-verify] [--special-folder FOLDER] [--path PATH]
149
150
  [--show-progress] [--connection-timeout SECONDS]
150
151
  [--read-timeout SECONDS] [--max-retries RETRIES]
151
- [--retry-delay SECONDS] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC]
152
- [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
153
- [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
154
- [--show-tags] [-d] [-T] [-q] [-Q]
152
+ [--retry-delay SECONDS] [--create-custom-json] [-t TIMESTAMP] [-f FFMPEG]
153
+ [-o OPUSENC] [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
154
+ [-A] [-k] [-u] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
155
+ [--show-tags] [-S] [-F] [-X] [-d] [-T] [-q] [-Q]
155
156
  SOURCE [TARGET]
156
157
 
157
158
  Create Tonie compatible file from Ogg opus file(s).
@@ -177,6 +178,7 @@ TeddyCloud Options:
177
178
  Maximum number of retry attempts (default: 3)
178
179
  --retry-delay SECONDS
179
180
  Delay between retry attempts in seconds (default: 5)
181
+ --create-custom-json Fetch and update custom Tonies JSON data
180
182
 
181
183
  optional arguments:
182
184
  -h, --help show this help message and exit
@@ -197,10 +199,10 @@ optional arguments:
197
199
  Save output files in the source directory instead of output directory
198
200
  -A, --auto-download Automatically download FFmpeg and opusenc if needed
199
201
  -k, --keep-temp Keep temporary opus files in a temp folder for testing
202
+ -u, --use-legacy-tags Use legacy hardcoded tags instead of dynamic TonieToolbox tags (DEPRECATED)
200
203
  -C, --compare FILE2 Compare input file with another .taf file for debugging
201
204
  -D, --detailed-compare
202
205
  Show detailed OGG page differences when comparing files
203
-
204
206
  Media Tag Options:
205
207
  -m, --use-media-tags Use media tags from audio files for naming
206
208
  --name-template TEMPLATE
@@ -220,6 +222,7 @@ Logging Options:
220
222
  -T, --trace Enable trace logging (very verbose)
221
223
  -q, --quiet Show only warnings and errors
222
224
  -Q, --silent Show only errors
225
+ --log-file Save logs to a timestamped file in .tonietoolbox folder
223
226
  ```
224
227
 
225
228
  ### Common Usage Examples
@@ -264,6 +267,29 @@ tonietoolbox input.mp3 --timestamp ./reference.taf # Reference TAF for extracti
264
267
  tonietoolbox input.mp3 --bitrate 128
265
268
  ```
266
269
 
270
+ #### Constant bitrate encoding:
271
+
272
+ For more predictable file sizes and consistent quality, use constant bitrate (CBR) encoding:
273
+
274
+ ```
275
+ # Encode with constant bitrate at 96 kbps (default)
276
+ tonietoolbox input.mp3 --cbr
277
+
278
+ # Encode with constant bitrate at 128 kbps
279
+ tonietoolbox input.mp3 --cbr --bitrate 128
280
+ ```
281
+
282
+ #### Append Tonie tag:
283
+
284
+ You can append a hexadecimal tag to the filename, which is useful for organizing Tonie files:
285
+
286
+ ```
287
+ # Add an 8-character hex tag to filename
288
+ tonietoolbox input.mp3 --append-tonie-tag 7F8A6B2E
289
+
290
+ # The output will be named "input-7F8A6B2E.taf"
291
+ ```
292
+
267
293
  #### Process a complex folder structure:
268
294
 
269
295
  Process an audiobook series with multiple folders:
@@ -278,6 +304,127 @@ Process a music collection with nested album folders and save TAF files alongsid
278
304
  tonietoolbox --recursive --output-to-source "\Hörspiele\"
279
305
  ```
280
306
 
307
+ #### Automatic dependency download:
308
+
309
+ If FFmpeg or opusenc are not found in your PATH, TonieToolbox can automatically download them:
310
+
311
+ ```
312
+ # Automatically download dependencies when needed
313
+ tonietoolbox input.mp3 --auto-download
314
+
315
+ # Specify custom FFmpeg or opusenc locations
316
+ tonietoolbox input.mp3 --ffmpeg "C:\path\to\ffmpeg.exe" --opusenc "C:\path\to\opusenc.exe"
317
+ ```
318
+
319
+ #### Keep temporary files:
320
+
321
+ When troubleshooting or debugging, you can keep the temporary opus files:
322
+
323
+ ```
324
+ # Keep temporary opus files in the temp folder
325
+ tonietoolbox input.mp3 --keep-temp
326
+
327
+ ```
328
+
329
+ #### Working with list files:
330
+
331
+ Create a text file (.lst) with paths to audio files for batch processing:
332
+
333
+ ```
334
+ # Contents of playlist.lst:
335
+ C:\Music\song1.mp3
336
+ "C:\Music\song2.flac"
337
+ C:\Music\song3.wav
338
+ "C:\Music Path With Spaces\song2.flac"
339
+
340
+ # Process the list file
341
+ tonietoolbox playlist.lst my_playlist.taf
342
+ ```
343
+
344
+ #### TeddyCloud advanced options:
345
+
346
+ Customize your TeddyCloud uploads with connection options:
347
+
348
+ ```
349
+ # Upload with custom timeouts and retry parameters
350
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --connection-timeout 20 --read-timeout 600 --max-retries 5 --retry-delay 10
351
+
352
+ # Disable progress bar during upload
353
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --show-progress=False
354
+
355
+ # Upload to a special folder in TeddyCloud
356
+ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --special-folder library
357
+ ```
358
+
359
+ #### Get available tags from TeddyCloud:
360
+
361
+ To see which tags you can use with your TeddyCloud server:
362
+
363
+ ```
364
+ tonietoolbox --get-tags https://teddycloud.example.com
365
+ ```
366
+
367
+ #### Version checking and updates:
368
+
369
+ TonieToolbox can check for newer versions and notify you when there are updates available:
370
+
371
+ ```
372
+ # Skip checking for updates if you're offline or want faster startup
373
+ tonietoolbox input.mp3 --skip-update-check
374
+
375
+ # Force refresh of version information from PyPI
376
+ tonietoolbox input.mp3 --force-refresh-cache
377
+
378
+ # Clear cached version information
379
+ tonietoolbox --clear-version-cache
380
+ ```
381
+
382
+ #### Legacy tag options:
383
+
384
+ Use legacy hardcoded tags instead of dynamic TonieToolbox tags:
385
+
386
+ ```
387
+ tonietoolbox input.mp3 --use-legacy-tags
388
+ ```
389
+
390
+ #### Create custom JSON data:
391
+
392
+ When uploading to TeddyCloud, you can also update the custom Tonies JSON data with information about the uploaded file:
393
+
394
+ ```
395
+ tonietoolbox input.mp3 --upload https://teddycloud.example.com --create-custom-json
396
+ ```
397
+
398
+ This will fetch and update the custom Tonies JSON data in the TeddyCloud server with information from your audio files.
399
+
400
+ #### Logging and Troubleshooting:
401
+
402
+ Control the verbosity of console output with different logging levels:
403
+
404
+ ```
405
+ # Enable detailed debug information (useful for troubleshooting)
406
+ tonietoolbox input.mp3 --debug
407
+
408
+ # Enable extremely verbose trace logging (developer level)
409
+ tonietoolbox input.mp3 --trace
410
+
411
+ # Reduce output to show only warnings and errors
412
+ tonietoolbox input.mp3 --quiet
413
+
414
+ # Show only critical errors (minimal output)
415
+ tonietoolbox input.mp3 --silent
416
+ ```
417
+
418
+ You can combine logging options with other commands:
419
+
420
+ ```
421
+ # Debug mode while splitting a TAF file
422
+ tonietoolbox --split my_tonie.taf --debug
423
+
424
+ # Quiet mode while batch processing
425
+ tonietoolbox --recursive "Music/Collection/" --quiet
426
+ ```
427
+
281
428
  ### Media Tags
282
429
 
283
430
  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.
@@ -383,6 +530,52 @@ tonietoolbox my_tonie.taf --upload https://teddycloud.example.com --ignore-ssl-v
383
530
 
384
531
  Use this option if the TeddyCloud server uses a self-signed certificate.
385
532
 
533
+ ## Real-World Use Cases
534
+
535
+ ### Converting an Audiobook Series
536
+
537
+ To convert an entire audiobook series with proper metadata and upload to TeddyCloud:
538
+
539
+ ```
540
+ 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"
541
+ ```
542
+
543
+ This command will:
544
+ 1. Recursively process the Die Drei Fragezeichen audioplays directory
545
+ 2. Use a naming template based on source metadata
546
+ 3. Encode at 128 kbps
547
+ 4. Upload both audio files and cover art to TeddyCloud
548
+
549
+ ### Creating Children's Story Collections
550
+
551
+ For a custom children's story collection with chapters:
552
+
553
+ ```
554
+ tonietoolbox story_collection.lst kids_stories.taf --bitrate 96 --cbr --auto-download --use-media-tags --name-template "{title} Stories" --debug
555
+ ```
556
+
557
+ This command:
558
+ 1. Processes a list of story audio files
559
+ 2. Names the output based on metadata
560
+ 3. Uses constant bitrate encoding for consistent quality
561
+ 4. Automatically downloads dependencies if needed
562
+ 5. Shows detailed debug information during the process
563
+
564
+
565
+ ### Advanced Media Tag Usage
566
+
567
+ For complex media tag processing:
568
+
569
+ ```
570
+ # First check available tags
571
+ tonietoolbox --show-tags "C:\Music\Classical\Bach"
572
+
573
+ # Then use a sophisticated naming template
574
+ tonietoolbox "C:\Music\Classical\Bach" --use-media-tags --name-template "{composer} - {opus} in {key} ({conductor}, {orchestra})"
575
+ ```
576
+
577
+ The first command shows what tags are available, allowing you to create precise naming templates for classical music collections as example.
578
+
386
579
  ## Technical Details
387
580
 
388
581
  ### TAF (Tonie Audio Format) File Structure
@@ -2,4 +2,4 @@
2
2
  TonieToolbox - Convert audio files to Tonie box compatible format
3
3
  """
4
4
 
5
- __version__ = '0.3.0'
5
+ __version__ = '0.4.0'
@@ -19,6 +19,7 @@ from .version_handler import check_for_updates, clear_version_cache
19
19
  from .recursive_processor import process_recursive_folders
20
20
  from .media_tags import is_available as is_media_tags_available, ensure_mutagen
21
21
  from .teddycloud import upload_to_teddycloud, get_tags_from_teddycloud, get_file_paths
22
+ from .tonies_json import fetch_and_update_tonies_json
22
23
 
23
24
  def main():
24
25
  """Entry point for the TonieToolbox application."""
@@ -50,7 +51,9 @@ def main():
50
51
  help='Maximum number of retry attempts (default: 3)')
51
52
  teddycloud_group.add_argument('--retry-delay', type=int, metavar='SECONDS', default=5,
52
53
  help='Delay between retry attempts in seconds (default: 5)')
53
-
54
+ teddycloud_group.add_argument('--create-custom-json', action='store_true',
55
+ help='Fetch and update custom Tonies JSON data')
56
+
54
57
  parser.add_argument('input_filename', metavar='SOURCE', type=str, nargs='?',
55
58
  help='input file or directory or a file list (.lst)')
56
59
  parser.add_argument('output_filename', metavar='TARGET', nargs='?', type=str,
@@ -104,6 +107,8 @@ def main():
104
107
  log_level_group.add_argument('-T', '--trace', action='store_true', help='Enable trace logging (very verbose)')
105
108
  log_level_group.add_argument('-q', '--quiet', action='store_true', help='Show only warnings and errors')
106
109
  log_level_group.add_argument('-Q', '--silent', action='store_true', help='Show only errors')
110
+ log_group.add_argument('--log-file', action='store_true', default=False,
111
+ help='Save logs to a timestamped file in .tonietoolbox folder')
107
112
 
108
113
  args = parser.parse_args()
109
114
 
@@ -111,6 +116,7 @@ def main():
111
116
  if args.input_filename is None and not (args.get_tags or args.upload):
112
117
  parser.error("the following arguments are required: SOURCE")
113
118
 
119
+ # Set up the logging level
114
120
  if args.trace:
115
121
  from .logger import TRACE
116
122
  log_level = TRACE
@@ -123,12 +129,15 @@ def main():
123
129
  else:
124
130
  log_level = logging.INFO
125
131
 
126
- setup_logging(log_level)
132
+ setup_logging(log_level, log_to_file=args.log_file)
127
133
  logger = get_logger('main')
128
134
  logger.debug("Starting TonieToolbox v%s with log level: %s", __version__, logging.getLevelName(log_level))
129
135
 
136
+ # Log the command-line arguments at trace level for debugging purposes
137
+ logger.log(logging.DEBUG - 1, "Command-line arguments: %s", vars(args))
130
138
 
131
139
  if args.clear_version_cache:
140
+ logger.log(logging.DEBUG - 1, "Clearing version cache")
132
141
  if clear_version_cache():
133
142
  logger.info("Version cache cleared successfully")
134
143
  else:
@@ -141,18 +150,24 @@ def main():
141
150
  force_refresh=args.force_refresh_cache
142
151
  )
143
152
 
153
+ logger.log(logging.DEBUG - 1, "Update check results: is_latest=%s, latest_version=%s, update_confirmed=%s",
154
+ is_latest, latest_version, update_confirmed)
155
+
144
156
  if not is_latest and not update_confirmed and not (args.silent or args.quiet):
145
157
  logger.info("Update available but user chose to continue without updating.")
146
158
 
147
159
  # Handle get-tags from TeddyCloud if requested
148
160
  if args.get_tags:
161
+ logger.debug("Getting tags from TeddyCloud: %s", args.get_tags)
149
162
  teddycloud_url = args.get_tags
150
163
  success = get_tags_from_teddycloud(teddycloud_url, args.ignore_ssl_verify)
164
+ logger.log(logging.DEBUG - 1, "Exiting with code %d", 0 if success else 1)
151
165
  sys.exit(0 if success else 1)
152
166
 
153
167
  # Handle upload to TeddyCloud if requested
154
168
  if args.upload:
155
169
  teddycloud_url = args.upload
170
+ logger.debug("Upload to TeddyCloud requested: %s", teddycloud_url)
156
171
 
157
172
  if not args.input_filename:
158
173
  logger.error("Missing input file for --upload. Provide a file path as SOURCE argument.")
@@ -162,6 +177,7 @@ def main():
162
177
  if os.path.exists(args.input_filename) and (args.input_filename.lower().endswith('.taf') or
163
178
  args.input_filename.lower().endswith(('.jpg', '.jpeg', '.png'))):
164
179
  # Direct upload of existing TAF or image file
180
+ logger.debug("Direct upload of existing TAF or image file detected")
165
181
  # Use get_file_paths to handle Windows backslashes and resolve the paths correctly
166
182
  file_paths = get_file_paths(args.input_filename)
167
183
 
@@ -191,10 +207,12 @@ def main():
191
207
  else:
192
208
  logger.info("Successfully uploaded %s to TeddyCloud", file_path)
193
209
 
210
+ logger.log(logging.DEBUG - 1, "Exiting after direct upload with code 0")
194
211
  sys.exit(0)
195
212
 
196
213
  # If we get here, it's not a TAF or image file, so continue with normal processing
197
214
  # which will convert the input files and upload the result later
215
+ logger.debug("Input is not a direct upload file, continuing with conversion workflow")
198
216
  pass
199
217
 
200
218
  ffmpeg_binary = args.ffmpeg
@@ -614,5 +632,49 @@ def main():
614
632
  else:
615
633
  logger.warning("No artwork found to upload")
616
634
 
635
+ # Handle create-custom-json option
636
+ if args.create_custom_json and args.upload:
637
+ teddycloud_url = args.upload
638
+ artwork_url = None
639
+
640
+ # If artwork was uploaded, construct its URL for the JSON
641
+ if args.include_artwork:
642
+ taf_basename = os.path.splitext(os.path.basename(out_filename))[0]
643
+ artwork_ext = None
644
+
645
+ # Try to determine the artwork extension by checking what was uploaded
646
+ source_dir = os.path.dirname(files[0]) if files else None
647
+ if source_dir:
648
+ from .media_tags import find_cover_image
649
+ artwork_path = find_cover_image(source_dir)
650
+ if artwork_path:
651
+ artwork_ext = os.path.splitext(artwork_path)[1]
652
+
653
+ # If we couldn't determine extension from a found image, default to .jpg
654
+ if not artwork_ext:
655
+ artwork_ext = ".jpg"
656
+
657
+ # Construct the URL for the artwork based on TeddyCloud structure
658
+ artwork_path = args.path or "/custom_img"
659
+ if not artwork_path.endswith('/'):
660
+ artwork_path += '/'
661
+
662
+ artwork_url = f"{teddycloud_url}{artwork_path}{taf_basename}{artwork_ext}"
663
+ logger.debug("Using artwork URL: %s", artwork_url)
664
+
665
+ logger.info("Fetching and updating custom Tonies JSON data")
666
+ success = fetch_and_update_tonies_json(
667
+ teddycloud_url,
668
+ args.ignore_ssl_verify,
669
+ out_filename,
670
+ files,
671
+ artwork_url
672
+ )
673
+
674
+ if success:
675
+ logger.info("Successfully updated custom Tonies JSON data")
676
+ else:
677
+ logger.warning("Failed to update custom Tonies JSON data")
678
+
617
679
  if __name__ == "__main__":
618
680
  main()