/
TODO
6471 lines (6416 loc) · 213 KB
/
TODO
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This file is formatted for Emacs' org-mode (see http://www.orgmode.org)
To view it properly, open it in Emacs 23.x and type: M-x org-mode
* Previous Issues
** DONE Fix WAVE/MP3 formats to support MP3 audio in a WAVE container
Instead of WaveAudio generating a nasty "compression not supported" error,
its is_type() classmethod should return False.
And, MP3Audio's is_type() classmethod should check for MP3 compressed
RIFF WAVE containers.
This isn't likely to mess up decoding, but may confuse ID3 tagging.
** DONE Allow file template to be specified on the command line
When making new files with track2track, cd2track, etc.
** DONE Update the website with the latest documentation
** DONE Allow a unified %(album_track_number)s file template field
If there's no album number, it's simply 2 digits of track number.
Otherwise, it's a combination of the two fields.
For example, album_number = 2 and track_number = 13 results in
"213" for a value.
** DONE Update trackcat to take a cuesheet argument when outputting FLACs
Thus, one can perform:
trackcat --cuesheet=file.cue file1.wav file2.wav file3.wav -t flac -o cd.flac
which will embed "file.cue" into "cd.flac" using metaflac.
Though no other format I'm aware of supports this kind of cuesheet handling,
being able to easily build solid disc images of a single FLAC file
is much of the reason for trackcat/tracksplit.
** DONE Don't remove undone tracklint entries from its undo DB
Since its checksum will change anyway and no longer match,
explicitly removing the entry is no longer necessary
** DONE Support FLAC padding
If changes to FLAC metadata are small enough, write over the
padding (if present) rather than rewrite the whole file - like metaflac.
This approach should speed up tagging considerably.
** DONE Fix image support in ID3v2
Very large images can take a very long time to load.
** DONE Fix programs to key on album number and track number
Certain programs, such as trackcmp, work on tracks across two directories
and key on track number to determine which to compare to which.
These need to be updated to use both track number and album number.
** DONE Adjust wave conversions to use album number, if present
For example, converting track_number 15 and album_number 2 to WAVE
should make a file "track215.cdda.wav" which then properly converts
back to track_number 15 and album_number 2 if read.
** DONE Improve XMCD handling
Support for XMCD files often breaks down if one or more tracks
are missing.
In some cases, there's no fix to be had (track2xmcd)
but in most instances it should be made to work correctly.
** DONE Perform type inference wherever possible
Anything with a single output file (trackcat and record2track)
should be able to infer its output type from the track suffix, if possible.
** DONE Add "comment" field support to all metadata types
Don't forget to add unit tests for comment field.
*** TODO Sort "comment" fields correctly across all metadata types
*** TODO Add --comment support to tracktag
** DONE Fix ID3v2 image support to handle Unicode descriptions
The current implementation falls down on UTF-16 input,
but I should have a solution from the COMM frame handler.
** DONE Limit ID3v2.2/2.3 to UCS-2 encoding
The current implementation treats UCS-2 the same as UTF-16.
This needs to be fixed so that really high unicode characters
(above U+FFFF) are replaced with something within spec.
** DONE Unify ID3v2 frame handling
In the beginning, there were text frames and Everything Else.
Text frames were unicode strings,
and Everything Else was a binary string of whatever.
Now that ID3 is cluttered with APIC frames and COMM frames that need
special treatment, ID3v2 needs an overhaul to more resemble FlacMetaData.
*** DONE Ensure unknown frames are displayed correctly
Anything that's not text, images or comments should get some sort
of proper display instead of a Python object string.
** DONE Add app testing to the unit test suite
Though not everything is unit-testable
(such as the CD handling programs or anything X11)
a lot of the batch programs are to some degree:
- [X] coverdump
- [X] track2track
- [X] trackcat
- [X] trackcmp
- [X] tracklength
- [X] tracklint
- [X] trackrename
- [X] tracksplit
- [X] tracktag
** DONE Add verbosity levels to programs
Every batch program should support a -V --verbose flag
with options for "silence","normal" (the default) and "debug".
Silence shuts off everything but error messages.
Normal is standard output behavior.
Debug for additional debugging output.
- [X] cd2track
- [X] cd2xmcd
- [X] coverdump
- [X] record2track
- [X] track2cd (this will need to forward verbosity to cdrecord)
- [X] track2track
- [X] track2xmcd
- [X] trackcmp
- [X] trackrename
- [X] tracksplit
- [X] tracktag
- [X] tracklint
** DONE Add compression percentage display to trackinfo
Though not massively useful, it'd be neat to see just how
compressed audio tracks are, as a percentage of their original size.
** DONE Add support for W??? frames to ID3v2
The various W??? frames are really just URLs and don't need to
be displayed as hex-encoded blobs.
** DONE Add CUE/TOC support to track2cd
It should be possible to burn a selection of tracks, or a disc image,
from a cuesheet with all its indexes/ISRC/catalog data intact
by passing --cue to track2cd.
** DONE Unify CUE/TOC support
Cuesheets and cdrdao TOC files are largely interchangeable.
They both feature a listing of track offsets and, optionally,
CD-TEXT data, ISRCs and so on.
These formats should be unified such that any program will
handle them both automatically.
- [X] tracksplit
- [X] trackcat
- [X] tracktag
*** DONE Update docs to mention CUE/TOC interchangeability
- [X] tracksplit
- [X] trackcat
- [X] tracktag
*** DONE Support cuesheet from FlacMetaData directly
Since we're parsing CUE/TOC files anyway, this data can be used
to build FLAC CUESHEET blocks directly instead of punting
this task to metaflac.
*** DONE Add unit tests for TOC/CUE files, as well as embedded FLAC cuesheets
** DONE Update copyright text for 2009
** DONE Preserve metadata when using trackcat
Any fields shared by all tracks should be merged into metadata
for the newly combined track.
** DONE Don't route data though WAVE files unless necessary
Currently, track2track routes through WAVE if both ends happen to
support foreign RIFF chunks, whether the files have such chunks or not.
This behavior needs to be modified such that only source files
which actually have foreign chunks, and a target format that supports them,
results in a pass through RIFF WAVE.
** DONE Convert editxmcd to PyGTK
Although the dialog(1)-based version works in terminals and is curses-based,
it's extremely hokey, error-prone and doesn't support any cut & paste.
This needs to be reimplemented in PyGTK (since coverview already uses it)
and made into a stable app someone would want to use.
*** DONE Update XMCD support
The current handling of XMCD files treats them only as very primative
AlbumMetaData implementations. This must be updated into something
round-trippable if editxmcd is to be modernized.
**** DONE Add XMCD unit tests
**** DONE Update XMCD API documentation
** DONE Require Python 2.5
Since Python 2.4 is in bugfix-only mode and barely supported,
it's best to move the minimum version to Python 2.5 or better
(which has already been superceded by Python 2.6).
This reduces the amount of Python versions to test on
and allows the use of more modern Python features which
makes the code less clunky.
*** TODO Update documentation to mention Python 2.5 requirement.
** DONE Expand WavPack's APEv2 tag coverage
WavPack's official specification defines APEv2 tags such as
"Cuesheet" and "Cover Art" which the APEv2 standard does not.
It would be helpful to make WavPack's APEv2 tags a superset of regular APEv2.
*** DONE Add image support to WavePackAPEv2
*** DONE Add cuesheet support to WavePackAPEv2
** DONE Build unified cuesheet interface
Once both FLAC and WavPack support embedded cuesheets,
there will need to be a unified interface to support them.
I expect this will be a simple pair of get_cuesheet/set_cuesheet
methods, probably attached to the AudioFiles themselves
rather than to MetaData objects.
*** DONE Alter FLAC-specific cuesheet documentation to be more general
*** DONE Ensure cuesheets are transferred properly when transcoding
*** DONE Update trackcat to use the interface
*** DONE Update tracksplit to use the interface
*** DONE Update track2cd to use the interface
*** DONE Document cuesheet interface
*** DONE Add unit tests for embedded cuesheets across all formats
*** DONE Add cuesheet import option to tracktag
This can also use the --cue flag,
for consistency with other image-handling programs like tracksplit.
If given with a single, album-length track, --cue will import a cuesheet.
If given with multiple tracks or a single track that's too short,
--cue will function like --xmcd and act as a metadata source.
*** DONE Update track2xmcd to support getting an XMCD file from CD image
** DONE Convert to Muspack SV8
Now that Musepack SV8 is finalized, it should be the new default.
The old SV7 command-line tools aren't well supported and don't
seem to work outside of x86 platforms.
SV7 streams are, in theory, backwards compatible so switching
shouldn't be a problem.
** DONE Update coverview to look more standard
It's currently a haphazard assortment of widgets
rather than anything like a proper GTK app.
It should be tweaked to look better.
** DONE Improve transcoding robustness
Just about all of the to_pcm() and from_pcm() methods expect
that their subprocess calls will work as expected.
Though rare in practice, these need to be checked in case
the child processes fail for any reason.
*** DONE Check for invalid input/output files/permissions errors
If an output file can't be read/written to for some reason
(invalid permissions, etc.) generate a proper error message
instead of throwing ugly IOExceptions or confusing errors.
- [X] cd2track
- [X] cd2xmcd
- [X] coverdump
- [X] editxmcd
- [X] record2track
- [X] track2cd
- [X] track2track
- [X] track2xmcd
- [X] trackcat
- [X] trackcmp
- [X] trackinfo
- [X] tracklength
- [X] tracklint
- [X] trackplay
- [X] trackrename
- [X] tracksplit
- [X] tracktag
** DONE Make text output consistent
Currently, command-line programs generate output using a
selection of scattered print statements - often accompanied by
if blocks when verbosity is indicated - and haphazardly
filtered through unicode.
This should be replaced by a unified message system similar
to Python's built-in logging module which can abstract away
these difficulties.
*** DONE Convert tty output to gettext-based strings
This will not only make output messages more consistent across the tools,
but will also allow for foreign language translations in the future.
- [X] cd2track
- [X] cd2xmcd
- [X] coverdump
- [X] record2track
- [X] track2cd
- [X] track2track
- [X] track2xmcd
- [X] trackcat
- [X] trackcmp
- [X] trackinfo
- [X] tracklength
- [X] tracklint
- [X] trackplay
- [X] trackrename
- [X] tracksplit
- [X] tracktag
**** DONE Convert output from audiotools module to gettext-based strings
- [X] __aiff__.py
- [X] __ape__.py
- [X] __au__.py
- [X] cue.py
- [X] __flac__.py
- [X] __freedb__.py
- [X] __id3__.py
- [X] __id3v1__.py
- [X] __image__.py
- [X] __init__.py
- [X] __m4a__.py
- [X] __mp3__.py
- [X] __musepack__.py
- [X] __speex__.py
- [X] toc.py
- [X] __vorbiscomment__.py
- [X] __vorbis__.py
- [X] __wavpack__.py
- [X] __wav__.py
*** DONE Add unit tests for tty output
All programs which generate output should be unit tested
so that all code paths are assured of printing the messages they're
supposed to print, at the streams they're supposed to print on,
and in the proper encoding settings.
- [X] coverdump
- [X] track2track
- [X] track2xmcd
- [X] trackcat
- [X] trackcmp
- [X] trackinfo
- [X] tracklength
- [X] tracklint
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Convert --help output to gettext-based strings
*** DONE Convert GUI programs to gettext-based strings
- [X] coverview
- [X] editxmcd
*** DONE Convert "Usage" output to gettext-based strings
** DONE Update tracksplit's man page
It now supports more of track2track's options
** DONE Support total tracks/total albums metadata fields
*** DONE Add support for fields in the metadata tags
- [X] Add support in Vorbis Comments
- [X] Add support in ID3v2
- [X] Add support in M4A
- [X] Add support in APEv2
*** DONE Add support in utilities
- [X] Add support in tracktag
- [X] Add support in cd2track
- [X] Add support in tracksplit
- [X] Add support in trackcat
*** DONE Add unit tests
*** DONE Add fields to --format output
*** DONE Update man pages with fields information
** DONE Integrate better MetaData merging
There's a few areas in which MetaData from multiple sources must
be merged in an intelligent manner,
such as where tracksplit takes a source track an XMCD file.
Now that a preliminary MetaData.merge() classmethod is in place,
this process must be integrated consistently.
- [X] track2track
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Add unit tests for MetaData merging process
- [X] track2track
- [X] trackrename
- [X] tracksplit
- [X] tracktag
** DONE Improve M4A metadata handling
*** DONE Make M4A metadata updating less destructive
Like FLAC, not all fields need to be wiped out when overwriting
old metadata with new.
*** DONE Add more M4A-specific unit tests
** DONE Add more system information to audiotools-config
All BIN-referenced binaries should be accounted for.
Thumbnailing status and requirements should be shown.
** DONE Add cdinfo utility
Analagous to trackinfo, but for an inserted CD.
This would be a better location for cd2xmcd's "-i" option.
*** DONE Add cdinfo man page
*** DONE Link cdinfo man page to other utility man pages
** DONE Add manual page for audiotools.cfg
It'll be easier to check what the options are from a man page
rather than having to check the website or PDF doc.
** DONE Convert vorbiscomment dependency to Python
This would remove the last app-based MetaData-setting utility
and may pave the way for adding cover art to Ogg Vorbis
(assuming I can find the standard for a secondary stream of image data)
** DONE Add metadata deletion capability
It would be helpful to have the low-level capability of deleting
either part of a MetaData tag or the entire tag altogether.
For example, deleting the "track_name" field would delete
a Vorbis comment's "TITLE" field.
Or, deleting the MetaData from MP3 would remove all the ID3v2/ID3v1 tags.
*** DONE Add delattr to ID3v1
** DONE Integrate pyconstruct as a submodule
** DONE Add undo capability to editxmcd
** DONE Add --cue option to track2xmcd
One should be able to pull metadata from CD images
without having to embed the cuesheet.
*** DONE Add unit tests for track2xmcd's --cue option
*** DONE Update man page
** DONE Group --help output more intelligently
For tools with a large number of options (such as track2track or tracktag)
the --help output is particularly jumbled.
Use more of optparse's features to make this output clearer.
- [X] cd2track
- [X] cd2xmcd
- [X] track2track
- [X] track2xmcd
- [X] tracksplit
- [X] tracktag
** DONE Check for FLAC metadata chunk overflow
Although APEv2 and ID3 tags support very large objects (hundreds of MB),
FLAC metadata chunks have a maxmimum of about 16MB per chunk,
which may be hit accidentally.
** DONE Fix or replace Python's built-in aifc module
The current implementation suffers from bugs.
*** DONE Document AIFF better
** DONE Add MusicBrainz support
It would be helpful to have external metadata support beyond FreeDB,
since FreeDB is very primitive.
*** DONE Ensure that MusicBrainz is interchangeable with FreeDB/XMCD
**** DONE Unify track2xmcd/track2mb, cd2xmcd/cd2mb
Based on preliminary testing, MusicBrainz's output is better than FreeDB's
but its album coverage is not as broad.
In addition, nobody wants to run their albums through two separate tools
in order to extract metadata for tagging. The best solution is
for tools to try both and output the one that's most complete.
**** DONE Extend editxmcd to MusicBrainz XML
Although editxmcd was originally designed specifically for XMCD files
and MusicBrainz's XML format differs radically, no one should have to
know whether an album metadata file is one or the other.
Therefore, editxmcd should be extended with additional fields
to handle XML backend data if necessary.
**** DONE Handle multiple Release entries with single Disc ID
**** DONE Allow MusicBrainz XML output for new editxmcd files
FreeDB output should also be an option, however.
*** DONE Add MusicBrainz protocol/format documentation
*** DONE Add MusicBrainz-specific unit tests
- [X] track2track
- [X] track2xmcd
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Update --help text to indicate MusicBrainz compatibility
- [X] cd2xmcd
- [X] editxmcd
- [X] track2track
- [X] track2xmcd
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Update man pages to indiciate MusicBrainz compatibility
- [X] cd2xmcd
- [X] editxmcd
- [X] track2track
- [X] track2xmcd
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Update documentation with MusicBrainz config file fields
*** DONE Ensure missing XML fields are handled correctly
The MusicBrainz XML spec allows most fields to be missing altogether
(such as <title>). editxmcd should add these fields in the proper place
if necessary.
**** DONE Add unit tests for improperly reordered XML fields
** DONE Ensure .glade files are found
Not all systems place Python data files in the same locations.
** DONE Convert to_pcm()/from_pcm() to FrameList-based I/O
Passing specifically-sized blobs of binary data between conversion
routines worked well when those routines are little more than
subprocess black-boxes. However, this approach works less well
whenever actual sample values are required, or when processing is needed.
In those cases, going from integers to strings, converting the strings
back to integers for processing, then bouncing them into strings once
again becomes needless work.
A more sensible approach is to keep all data as FrameList-compatible
objects (stored as C-based lists of int32s behind-the-scenes)
and convert that data to/from strings only at the beginning and end
of processing.
*** DONE Build C-based audiotools.pcm.FrameList object
This needs to closely match audiotools.FrameList's functionality
and combine all the PCM conversion features from audiotools.pcmreader
**** DONE Integrate audiotools.pcm.FrameList with i_array structures
**** DONE Make audiotools.pcm.FrameList into a standalone object
So standalone test codecs can use them, such as "flacenc"
**** DONE Unit test audiotools.pcm.FrameList
*** DONE Convert FLAC encoder/decoder to use FrameList objects
- [X] flacenc
- [X] audiotools.decoders.FlacDecoder
- [X] audiotools.encoders.encode_flac
*** DONE Convert to_pcm()/from_pcm() routines to use FrameList objects
- [X] AAC
- [X] AIFF
- [X] Sun AU
- [X] FLAC
- [X] M4A
- [X] MP2
- [X] MP3
- [X] Ogg FLAC
- [X] Ogg Speex
- [X] WAVE
- [X] WavPack
*** DONE Convert CDTrackReader/OffsetCDTrackReader to use FrameList objects
*** DONE Convert PCMConverter to use FrameList objects
*** DONE Convert ReplayGainReader to use FrameList objects
*** DONE Ensure integrated FrameList passes all unit tests
*** DONE Remove deprecated audiotools.FrameList object
*** DONE Remove deprecated pcmstream.PCMStreamReader object
*** DONE Convert pcmstream module to resample module
*** DONE Avoid importing audiotools.pcm so often
Other C libraries often import audiotools.pcm via Python callbacks
This library importing should be cached when possible.
- [X] cdiomodule
- [X] pcmreader
- [X] replaygain
- [X] resample
*** DONE Check for memory leaks
*** DONE Add FrameList and FloatFrameList programming documentation
*** DONE Remove .copy() method
Since FrameLists are now immutable, there's no need for it
*** DONE Make pcm objects self-documenting
For example, their methods and functions should give useful info
when checked with "help()"
** DONE Add native ReplayGain handling routines
*** DONE Add native ReplayGain handling to FlacAudio/OggFlacAudio
*** DONE Ensure add_replay_gain()'s exceptions are caught
Errors during calculation may raise ValueError,
which must be caught anywhere the function is called
*** DONE Add ReplayGain unit tests
*** DONE Ensure ReplayGain works properly on 8bps and 24bps output
*** DONE Ensure ReplayGain is applied consistently
Although cd2track and tracksplit are guaranteed
to generate only one album at a time, track2track and tracktag are not.
If multiple albums are applied gain at once,
add_replay_gain must be called on an album-by-album basis
rather than on the entire set.
*** DONE Double-check ReplayGainReader
Ensure its output is consistent with other implementations.
** DONE Fix multi-channel audio handling
It's important that channel mapping information be preserved
when transcoding between sources with 3+ channels.
This likely means another flag for PCMReader so that
from_pcm() can build a file with the proper channel mask set.
However, it may also be necessary to build some sort of
channel reordering mechanism in the event that formats differ
on how channels are to be ordered in the file.
*** Channel Counts and Ordering
| Format | Maximum Channels | Ordering |
|------------+------------------+------------------------|
| AAC | 48 | stereo-only (via faac) |
| AIFF | 2^16 | predefined |
| Sun AU | 2^32 | mostly undefined |
| FLAC | 8 | as WAVE |
| M4A | 48 | as WAVE? |
| MP2 | 2 | stereo-only |
| MP3 | 2 | stereo-only |
| Musepack | 2 | stereo-only |
| Ogg FLAC | 8 | as WAVE |
| Ogg Vorbis | 255 | predefined |
| Ogg Speex | 2^32 | stereo-only |
| RIFF WAVE | 2^16 | predefined |
| WavPack | 16 | as WAVE |
|------------+------------------+------------------------|
*** DONE Fix AudioFile definitions to support channel_mask()
- [X] AACAudio
- [X] AiffAudio
- [X] AuAudio
- [X] FlacAudio
- [X] M4AAudio
- [X] MP2Audio
- [X] MP3Audio
- [X] OggFlacAudio
- [X] VorbisAudio
- [X] SpeexAudio
- [X] WaveAudio
- [X] WavPackAudio
*** DONE Fix to_pcm() methods to support channel_mask
- [X] AACAudio
- [X] AiffAudio
- [X] AuAudio
- [X] FlacAudio
- [X] M4AAudio
- [X] MP2Audio
- [X] MP3Audio
- [X] OggFlacAudio
- [X] VorbisAudio
- [X] SpeexAudio
- [X] WaveAudio
- [X] WavPackAudio
*** DONE Fix from_pcm() classmethods to support channel_mask
- [X] AACAudio
- [X] AiffAudio
- [X] AuAudio
- [X] FlacAudio
- [X] M4AAudio
- [X] MP2Audio
- [X] MP3Audio
- [X] OggFlacAudio
- [X] VorbisAudio
- [X] SpeexAudio
- [X] WaveAudio
- [X] WavPackAudio
*** DONE Fix alternate PCMReaders to support channel_mask
- [X] BufferedPCMReader
- [X] PCMConverter
- [X] ReplayGainReader
- [X] CDTrackReader
- [X] OffsetCDTrackReader
- [X] PCMCat
*** DONE Handle undefined channel masks in a sane way
**** DONE Fix to_pcm() methods to output undefined ChannelMasks
If a format has not defined channel assignments for a given
channel count, its to_pcm() method should return undefined ChannelMasks.
- [X] AACAudio
- [X] AiffAudio
- [X] AuAudio
- [X] FlacAudio
- [X] M4AAudio
- [X] MP2Audio
- [X] MP3Audio
- [X] OggFlacAudio
- [X] VorbisAudio
- [X] SpeexAudio
- [X] WaveAudio
- [X] WavPackAudio
**** DONE Fix from_pcm() classmethods to accept undefined ChannelMasks
So long as the number of channels is acceptable,
audio formats are free to place undefined ChannelMasks
in whatever arrangement they'd like.
- [X] AACAudio
- [X] AiffAudio
- [X] AuAudio
- [X] FlacAudio
- [X] M4AAudio
- [X] MP2Audio
- [X] MP3Audio
- [X] OggFlacAudio
- [X] VorbisAudio
- [X] SpeexAudio
- [X] WaveAudio
- [X] WavPackAudio
*** DONE Unit test multichannel encoding and channel_mask handling
**** DONE Ensure all AudioFile types have a working channel_mask() method
Even 2 channel audio should yield something valid.
**** DONE Ensure all to_pcm() methods yield a matching channel_mask attribute
**** DONE Ensure channel_mask is preserved between from_pcm(to_pcm()) calls
**** DONE Ensure channel_mask is preserved between to_wave()/from_wave() calls
**** DONE Ensure channels are actually stored in the proper order
This is less of an issue for .wav, .flac, .oga or .wv
which already store channels in RIFF WAVE order
and more of an issue for Ogg Vorbis and other formats that do not.
**** DONE Ensure UnsupportedChannelMask is raised when necessary
This includes calls to from_pcm() and from_wave()
*** DONE Ensure PCMReader.channel_mask is always an integer
** DONE Fix the unit test error messages
** DONE Make the programming documentation web-capable
It should render consistently with the regular Python reference docs
and be placed both in the source tree and on the website
for better accessability.
*** DONE Document audiotools
- [X] AudioFile
- [X] BufferedPCMReader
- [X] ChannelMask
- [X] ExecQueue
- [X] Image
- [X] MetaData
- [X] PCMConverter
- [X] PCMReader
- [X] PCMCat
- [X] ReorderedPCMReader
- [X] ReplayGain
- [X] ReplayGainReader
- [X] Messenger
- [X] AlbumMetaData
- [X] CDTrackLog
- [X] CDDA
- [X] CDTrackReader
- [X] calculate_replay_gain
- [X] filename_to_type
- [X] find_glade_file
- [X] group_tracks
- [X] open
- [X] open_directory
- [X] open_files
- [X] pcm_cmp
- [X] pcm_split
- [X] read_metadata_file
- [X] read_sheet
- [X] stripped_pcm_cmp
- [X] transfer_data
- [X] transfer_framelist_data
- [X] BIN
- [X] TYPE_MAP
- [X] VERSION
- [X] AVAILABLE_TYPES
*** DONE Document audiotools.pcm
- [X] FloatFrameList
- [X] FrameList
- [X] from_channels
- [X] from_float_channels
- [X] from_float_frames
- [X] from_frames
- [X] from_list
*** DONE Document audiotools.resample
- [X] Resampler
*** DONE Document audiotools.replaygain
- [X] ReplayGain
*** DONE Document audiotools.cdio
- [X] CDDA
- [X] set_read_callback
*** DONE Document audiotools.cue
- [X] Cuesheet
- [X] read_cuesheet
- [X] CueException
*** DONE Document audiotools.toc
- [X] TOCFile
- [X] read_tocfile
- [X] TOCException
** DONE Make reference documentation render consistently
*** DONE Ensure documents render in letter and A4 size
*** DONE Add Creative Commons licensing to source code and doc itself
*** DONE Add internal PDF linkage
The file should have working bookmarks
and internal links so one can click directly to a chapter
*** DONE Add new introduction
*** DONE Basics
**** DONE Hexadecimal
**** DONE Endianness
**** DONE Signed values
How to decode/encode signed integers should be properly explained
**** DONE Character Encodings
**** DONE PCM
*** DONE .wav
**** DONE the RIFF WAVE stream
**** DONE the fmt chunk
**** DONE the WAVEFORMATEXTENSIBLE fmt chunk
**** DONE the data chunk
**** DONE channel mapping
*** DONE .aiff
**** DONE the AIFF stream
**** DONE the COMM chunk
***** TODO 80 bit IEEE standard 754 floating point
**** DONE the SSND chunk
*** DONE .au
**** DONE the AU stream
**** DONE the AU header
*** DONE .flac
**** DONE the FLAC file stream
**** DONE FLAC metadata
***** DONE the PADDING metadata block
***** DONE the APPLICATION metadata block
***** DONE the SEEKTABLE metadata block
***** DONE the VORBIS_COMMENT metadata block
***** DONE the PICTURE metadata block
***** DONE the CUESHEET metadata block
**** DONE FLAC decoding
***** DONE the CONSTANT subframe
***** DONE the VERBATIM subframe
***** DONE the FIXED subframe
***** DONE the LPC subframe
***** DONE the Residual
****** DONE Rice Encoding
***** DONE Channels
***** DONE Wasted bits per sample
**** DONE FLAC encoding
***** DONE Metadata header
***** DONE the STREAMINFO metadata block
***** DONE Frame header
***** DONE Channel assignment
***** DONE Subframe header
***** DONE the CONSTANT subframe
***** DONE the VERBATIM subframe
***** DONE the FIXED subframe
***** DONE the LPC subframe
****** DONE Windowing
****** DONE Computing autocorrelation
****** DONE LP coefficient calculation
****** DONE Best order estimation
****** DONE Best order exhaustive search
****** DONE Quantizing coefficients
****** DONE Calculation Residual
***** DONE the Residual
****** DONE Residual Values
**** DONE the Checksums
***** TODO CRC-8
***** TODO CRC-16
*** DONE .ape
**** DONE the Monkey's Audio stream
**** DONE the APE Descriptor
**** DONE the APE Header
**** DONE the APEv2 tag
**** DONE the APEv2 tag header/footer
**** DONE the APEv2 flags
*** DONE .wv
**** DONE the WavPack file stream
**** DONE a WavPack block header
**** DONE a WavPack sub-block header
*** DONE .mp3
**** DONE the MP3 file stream
**** DONE an MPEG frame header
***** DONE the Xing header
**** DONE the ID3v1 tag
***** DONE ID3v1
***** DONE ID3v1.1
**** DONE the ID3v2 tag
***** DONE the ID3v2 stream
***** DONE ID3v2.2
****** DONE the ID3v2.2 Header
****** DONE an ID3v2.2 Frame
****** DONE ID3v2.2 Frame IDs
****** DONE the PIC Frame
***** DONE ID3v2.3
****** DONE the ID3v2.3 Header
****** DONE an ID3v2.3 Frame
****** DONE ID3v2.3 Frame IDs
****** DONE the APIC Frame
***** DONE ID3v2.4
****** DONE the ID3v2.4 Header
****** DONE an ID3v2.4 Frame
****** DONE ID3v2.4 Frame IDs
****** DONE the APIC Frame
*** DONE .ogg
**** DONE the Ogg file stream
**** DONE an Ogg Page
**** DONE Ogg packets
**** DONE the Identification packet
**** DONE the Comment packet
**** DONE Channel assignment
*** DONE .spx
**** DONE the Header packet
**** DONE the Comment packet
*** DONE .oga
**** DONE the Ogg FLAC file stream
**** DONE the STREAMINFO metadata packet
**** DONE the Metadata packets
*** DONE .m4a
**** DONE the QuickTime file stream
**** DONE a QuickTime atom
**** DONE Container atoms
**** DONE M4A atoms
***** DONE the ftyp atom
***** DONE the mvhd atom
***** DONE the tkhd atom
***** DONE the mdhd atom
***** DONE the hdlr atom
***** DONE the smhd atom
***** DONE the dref atom
***** DONE the stsd atom
***** DONE the mp4a atom
***** DONE the stts atom
***** DONE the stsc atom
***** DONE the stsz atom
***** DONE the stco atom
***** DONE the meta atom
****** DONE the trkn sub-atom
****** DONE the disk sub-atom
*** DONE .mpc
**** DONE Musepack SV7
***** DONE the Musepack SV7 file stream
***** DONE the Musepack SV7 header
**** DONE Musepack SV8
***** DONE the Musepack SV8 file stream
***** DONE Nut-encoded values
***** DONE the SH packet
***** DONE the SE packet
***** DONE the RG packet
***** DONE the EI packet
*** DONE FreeDB
**** DONE Native Protocol
***** DONE the Disc ID
***** DONE Initial Greeting
***** DONE Client-Server Handshake
***** DONE Set Protocol Level
***** DONE Query Database
***** DONE Read XMCD Data
***** DONE Close Connection
**** DONE Web Protocol
**** DONE XMCD
*** DONE MusicBrainz
**** DONE Searching Releases
***** DONE The Disc ID
***** DONE Server Query
***** DONE Release XML
**** DONE MusieBrainz XML
*** DONE ReplayGain
**** DONE Applying ReplayGain
**** DONE Calculating ReplayGain
***** DONE the Equal Loudness Filter
This should be re-documented to be closer to the actual implementation
****** TODO the Yule Filter
****** TODO the Buffer Filter
****** TODO a Filtering Example
***** DONE RMS Energy Blocks
***** DONE Statistical Processing and Calibration
*** DONE References
*** DONE Remove old troff reference documentation
*** DONE Add title and author to PDF documentation
** DONE Ensure make(1) from doc/ directory builds both doc trees
** DONE Seperate unreadable files from unknown files
Files we're unable to read should be handled differently
from files we're unable to understand.
*** DONE Update audiotools.open() to raise IOErrors
*** DONE Update audiotools.open_files() to handle IOErrors
*** DONE Update audiotools.open_directory() to handle IOErrors
*** DONE Update internal calls to open()/open_files() to handle IOErrors
- [X] __flac__.py
- [X] __m4a__.py
- [X] __mp3__.py
- [X] __vorbis__.py
- [X] __wavpack__.py
- [X] __wav__.py
*** DONE Update tools which use open()/open_files() to handle IOErrors
- [X] coverdump
- [X] editxmcd
- [X] track2cd
- [X] track2track
- [X] track2xmcd
- [X] trackcat
- [X] trackcmp
- [X] trackinfo
- [X] tracklength
- [X] tracklint
- [X] trackplay
- [X] trackrename
- [X] tracksplit
- [X] tracktag
*** DONE Add unit tests to demonstrate new behavior
*** DONE Update programming documentation with new behavior
** DONE Ensure embedded cuesheets aren't clobbered by adding more metadata
** DONE Adjust %(album_track_number)s to accomodate more than 9 albums
For example, track 2 of 7, album 5 of 11 in format
"%(album_track_number)s - %(track_name)s.%(suffix)s should be:
"0502 - name.suffix"
** DONE editxmcd's "New" command should work with embedded cuesheets
Selecting a single disc image with embedded cuesheets should
fill in the proper XMCD/MusicBrainz fields
** DONE Ensure add_replay_gain used on hi-def tracks doesn't raise errors
** DONE Add Shorten support
I don't expect people have a lot of shn files lying around
and nobody should be using it for new data
(though I'll add a rudimentary encoder for completeness' sake)
but it's interesting to document for historical reasons.
*** DONE Build complete decoder
- [X] DIFF0
- [X] DIFF1
- [X] DIFF2
- [X] DIFF3
- [X] QUIT
- [X] BLOCKSIZE
- [X] BITSHIFT
- [X] QLPC
- [X] ZERO
- [X] VERBATIM
I'll likely limit support to Shorten version2/3
since generating older versions will be a challenge
and this format is obscure enough as it is.
*** DONE Build partial encoder
- [X] DIFF0
- [X] DIFF1
- [X] DIFF2
- [X] QUIT
- [X] BLOCKSIZE
- [X] ZERO
- [X] VERBATIM
**** DONE Convert partial encoder for standalone use
To ensure there aren't any memory leaks
*** DONE Add ShortenAudio type to audiotools Python core
*** DONE Add Shorten-specific unit tests
*** DONE Document Shorten
- [X] Shorten data types
- [X] the Shorten file stream
- [X] the decoding process
- [X] the encoding process
** DONE trackcmp should give exact PCM frame/byte of first mismatch
*** DONE update unit tests to cover new behavior
- [X] test_trackcmp
- [X] test_trackcmp1
- [X] test_trackcmp2
- [X] test_trackcmp3
- [X] test_trackcmp4
*** DONE update manual page to cover new behavior
** DONE Add analyzers for built-in decoders
Analagous to flac(1)'s --analyze option,
this will be an .analyze_frame() method that returns a Python dict
of ints/lists/dicts containing frame data on each pass,
or None at the stream's end.
This will provide both an easier way to visualize the file's internals,
and also a debugging aid.
*** DONE FlacDecoder
*** DONE SHNDecoder
*** DONE ALACDecoder
** DONE Add more examples
A lot of handy new features aren't documented with examples and walkthroughs.
Examples to add include:
- [X] a full multi-CD example, detailing the use of --album-number
- [X] an image embedding walkthrough
- [X] a CD image creation, splitting, burning example involving TOC/CUE files
- [X] an XMCD walkthrough with fetching, editing and tagging
** DONE Update documentation to cover concrete MetaData classes
- [X] ApeTag
- [X] FlacMetaData
- [X] ID3v1Comment
- [X] ID3v22Comment
- [X] ID3v23Comment
- [X] ID3v24Comment
- [X] ID3CommentPair
- [X] M4AMetaData
- [X] VorbisComment
** DONE Ensure man pages install correctly on Mac OS X
** DONE add a %(basename)s --format attribute
For example, given the path: "/foo/bar/01 - track name.mp3"
the %(basename)s attribute would be: "01 - track name"
allowing one to ignore its internal metadata entirely
and use original names.
*** DONE Update AudioFile.track_name to support attribute
*** DONE Update tools that call AudioFile.track_name
- [X] cd2track
- [X] track2track
- [X] trackrename
- [X] tracksplit
*** DONE Update man pages for tools that call AudioFile.track_name
- [X] track2track.1
- [X] trackrename.1
- [X] audiotools.cfg.5
*** DONE Add unit test support for new attribute
*** DONE Add documentation for new field to programming reference
*** DONE Add documentation for format strings to programming reference
** DONE Update AudioFile.track_name classmethod
the previous behavior was a kludge cobbled together over time
Its new call method is: track_name(file_path, metadata, format)
so that track_number and album_number can be pulled from file_path
directly instead of passed in from outside.
*** DONE Update tools to support new calling method
- [X] track2track
- [X] cd2track
- [X] trackrename
- [X] tracksplit
*** DONE Update programming documentation
*** DONE Add unit tests
*** DONE Update old unit tests with new behavior
*** DONE unit test suffix field
** DONE Update Python code to support PEP 8
Following accepted Python style should make the code more
accessible and maintainable in the long run.
It's also a good opportunity to clean up and simplify code
without changing the actual API interface.
*** DONE Update core modules
**** DONE __aiff__.py