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.
- {tonietoolbox-0.3.0/TonieToolbox.egg-info → tonietoolbox-0.4.0}/PKG-INFO +199 -6
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/README.md +198 -5
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/__init__.py +1 -1
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/__main__.py +64 -2
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/audio_conversion.py +36 -14
- tonietoolbox-0.4.0/TonieToolbox/constants.py +90 -0
- tonietoolbox-0.4.0/TonieToolbox/logger.py +103 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/media_tags.py +22 -6
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/teddycloud.py +101 -2
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_file.py +32 -12
- tonietoolbox-0.4.0/TonieToolbox/tonies_json.py +502 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0/TonieToolbox.egg-info}/PKG-INFO +199 -6
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/SOURCES.txt +1 -0
- tonietoolbox-0.3.0/TonieToolbox/constants.py +0 -15
- tonietoolbox-0.3.0/TonieToolbox/logger.py +0 -57
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/LICENSE.md +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/MANIFEST.in +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/dependency_manager.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/filename_generator.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/ogg_page.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/opus_packet.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/recursive_processor.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_analysis.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_header.proto +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/tonie_header_pb2.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox/version_handler.py +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/dependency_links.txt +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/entry_points.txt +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/requires.txt +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/TonieToolbox.egg-info/top_level.txt +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/pyproject.toml +0 -0
- {tonietoolbox-0.3.0 → tonietoolbox-0.4.0}/setup.cfg +0 -0
- {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
|
+
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]
|
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]
|
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
|
@@ -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()
|