Added support for table of contents (CTOC) - fixes #2.

Added support for picture and url fields in chapter frames.
Updated unit tests.

Author: tolo

CHANGELOG.md

@@ -3,6 +3,8 @@
 ##Version 0.2.0
 
 ### Features
+* Added support for table of contents (CTOC). Resolved with input from [pull request 2](https://github.com/tolo/id3tag/issues/2), added by @szeidner.
+* Added support for picture and url fields in chapter frames (CHAP). Resolved with input from [pull request 2](https://github.com/tolo/id3tag/issues/2), added by @szeidner.
 * Enabled previously commented out support for unsync lyrics/transcription frames (USLT). Resolved with input from [pull request 3](https://github.com/tolo/id3tag/issues/3), added by @theckr96.
 
 ### Bug fixes

README.md

@@ -4,7 +4,7 @@ ID3Tag is a small library for reading common ID3 meta data from mp3-files and ot
 There are of course already other libraries for doing this out there, but at the time of creating this library, none of 
 them provided support in three critical areas: 
 
-- Reading **chapter** (`CHAP`) frames
+- Reading **chapter** (`CHAP`) and **table of contents** (`CTOC`) frames
 - Reading ID3 meta data without having to load the entire file into memory
 - Easy extensibility to be able to implement support for additional frame types
 
@@ -17,7 +17,8 @@ audio books was another motivating factor (hence support for chapters and large
 - Support for ID3 v2.3 (and above)
 - Support for common ID3 frames, such as:
     - Text information frames [see here](https://id3.org/id3v2.3.0#Text_information_frames) 
-    - Chapter frames, i.e. [`CHAP` frames](https://id3.org/id3v2-chapters-1.0)
+    - Chapter frames, i.e. [`CHAP` frames](https://id3.org/id3v2-chapters-1.0#Chapter_frame)
+    - Table of contents frames, i.e. [`CTOC` frames](https://id3.org/id3v2-chapters-1.0#Table_of_contents_frame)
     - Attached picture frames, i.e. [`APIC` frames](https://id3.org/id3v2.3.0#Attached_picture)
     - Comment frames, i.e. [`COMM` frames](https://id3.org/id3v2.3.0#Comments)
 
@@ -31,7 +32,9 @@ the ID3 tag from a file.
 final parser = ID3TagReader.path('path to a file');
 final tag = parser.readTagSync();
 print('Title: ${tag.title}');
-print('Chapters: ${tag.chapters}');
+print('All chapters: ${tag.chapters}');
+// Or: 
+print('Chapters in top level table of contents: ${tag.topLevelChapters}');
 ```
 
 During development, it may sometimes be convenient to use files in the form of asset resources. To accomplish this, you 
@@ -46,11 +49,6 @@ File(filePath).writeAsBytesSync(fileData.buffer.asUint8List(fileData.offsetInByt
 ```
 
 
-## On the horizon
-
-The plan is to add support for reading the table of contents (`CTOC`) frame type.
-
-
 ## Additional information
 
 This library was initially derived from the package [id3](https://github.com/sanket143/id3), but later refactored,

lib/src/extensions/iterable_extension.dart

@@ -13,3 +13,10 @@ extension IterableExtensions<E> on Iterable<E> {
     }
   }
 }
+
+extension ListExtensions<E> on List<E> {
+  bool addNotNull(E? element) {
+    if (element != null) add(element);
+    return element != null;
+  }
+}

lib/src/frames/chapter_frame.dart

@@ -1,7 +1,9 @@
+import '../raw_frame.dart';
 import 'frame.dart';
-import 'text_information_frame.dart';
 import 'frame_parser.dart';
-import '../raw_frame.dart';
+import 'text_information_frame.dart';
+import 'user_url_frame.dart';
+import 'picture_frame.dart';
 
 
 const String _frameName = 'CHAP';
@@ -15,19 +17,23 @@ class Chapter extends Frame {
   final String? description;
   final int startTimeMilliseconds;
   final int endTimeMilliseconds;
+  final Picture? picture;
+  final UserUrl? url;
 
   Chapter({required this.elementId, required this.title, this.description,
-    required this.startTimeMilliseconds, required this.endTimeMilliseconds});
+    required this.startTimeMilliseconds, required this.endTimeMilliseconds, this.picture, this.url});
 
   @override
   Map<String, dynamic> toDictionary() {
     return {
-      'frameName' : frameName,
-      'elementId' : elementId,
-      'title' : title,
-      'description' : description ?? '',
-      'startTimeMilliseconds' : startTimeMilliseconds,
-      'endTimeMilliseconds' : endTimeMilliseconds,
+      'frameName': frameName,
+      'elementId': elementId,
+      'title': title,
+      'description': description ?? '',
+      'startTimeMilliseconds': startTimeMilliseconds,
+      'endTimeMilliseconds': endTimeMilliseconds,
+      'picture': picture,
+      'url': url
     };
   }
 }
@@ -49,21 +55,24 @@ class ChapterFrameParser extends FrameParser<Chapter> {
 
     String? chapterName;
     String? chapterDescription;
+    Picture? picture;
+    UserUrl? url;
     if (frameContent.remainingBytes > 0) {
-      final subFrame1 = rawFrame.parseSubFrame();
-      final subFrame2 = rawFrame.parseSubFrame();
-
-      if (subFrame1 != null && subFrame1 is TextInformation) { // TIT2 or TIT3
-        chapterName = subFrame1.frameName == 'TIT2' ? subFrame1.value : null;
-        chapterDescription = subFrame1.frameName == 'TIT3' ? subFrame1.value : null;
-      }
-      if (subFrame2 != null && subFrame2 is TextInformation) { // TIT2 or TIT3
-        chapterName = subFrame2.frameName == 'TIT2' ? subFrame2.value : chapterName;
-        chapterDescription = subFrame2.frameName == 'TIT3' ? subFrame2.value : chapterDescription;
+      final subFrames = rawFrame.parseSubFrames();
+      for(var frame in subFrames) {
+        if (frame is TextInformation) { // TIT2 or TIT3
+          chapterName = frame.frameName == 'TIT2' ? frame.value : chapterName;
+          chapterDescription = frame.frameName == 'TIT3' ? frame.value : chapterDescription;
+        } else if (frame is Picture) {
+          picture = frame;
+        } else if (frame is UserUrl) {
+          url = frame;
+        }
       }
     }
 
     return Chapter(elementId: elementId, title: chapterName ?? elementId, description: chapterDescription,
-        startTimeMilliseconds: startTimeMilliseconds, endTimeMilliseconds: endTimeMilliseconds);
+        startTimeMilliseconds: startTimeMilliseconds, endTimeMilliseconds: endTimeMilliseconds,
+        picture: picture, url: url);
   }
 }

lib/src/frames/frames.dart

@@ -3,7 +3,7 @@ export 'comment_frame.dart';
 export 'frame.dart';
 export 'frame_parser.dart';
 export 'picture_frame.dart';
-//export 'table_of_contents_frame.dart';
+export 'table_of_contents_frame.dart';
 export 'text_information_frame.dart';
 //export 'url_frame.dart';
 export 'user_url_frame.dart';

lib/src/frames/table_of_contents_frame.dart

@@ -1,8 +1,63 @@
+import 'package:id3tag/src/frames/frames.dart';
 
-//const String _frameName = 'CTOC';
+import '../raw_frame.dart';
 
-// TODO
-class TableOfContentsFrameParser  {
-  // @override
-  //List<String> get frameNames => [_frameName];
+
+const String _frameName = 'CTOC';
+
+
+class TableOfContents extends Frame {
+  @override String get frameName => _frameName;
+
+  final String elementId;
+  final bool isTopLevel;
+  final bool isOrdered;
+  final List<String> childElementIds;
+  final String? description;
+
+  TableOfContents({required this.elementId, required this.isTopLevel, required this.isOrdered,
+    required this.childElementIds, this.description});
+
+  @override
+  Map<String, dynamic> toDictionary() {
+    return {
+      'frameName': frameName,
+      'elementId': elementId,
+      'topLevel': isTopLevel,
+      'ordered': isOrdered,
+      'description': description,
+      'childElementIds': childElementIds,
+    };
+  }
 }
+
+class TableOfContentsFrameParser extends FrameParser<TableOfContents> {
+  @override
+  List<String> get frameNames => [_frameName];
+
+  @override
+  TableOfContents? parseFrame(RawFrame rawFrame) {
+    final frameContent = rawFrame.frameContent;
+    final elementId = frameContent.readString(checkEncoding: false);
+    final flags = frameContent.readBytes(1);
+    final int entryCount = frameContent.readBytes(1).first;
+
+    List<String> childElementIds = [];
+    for (var i=0; i<entryCount; i++) {
+      childElementIds.add(frameContent.readString());
+    }
+
+    String? description;
+    if (frameContent.remainingBytes > 0) {
+      final subFrame = rawFrame.parseSubFrame();
+      if (subFrame is TextInformation) { // TIT2
+        description = subFrame.value;
+      }
+    }
+
+    return TableOfContents(elementId: elementId,
+      isTopLevel: (flags.first & 0x2) > 0, isOrdered: (flags.first & 0x1) > 0,
+      childElementIds: childElementIds, description: description,
+    );
+  }
+}

lib/src/id3_parser.dart

@@ -47,19 +47,19 @@ class ID3Parser implements ID3TagReader {
         _parsers = frameParsers, _id3TagBytes = id3TagBytes, _initialOffset = initialOffset;
 
   factory ID3Parser(File file, {Map<String, FrameParser>? frameParsers}) {
-    final RandomAccessFile _reader = file.openSync(mode: FileMode.read);
+    final RandomAccessFile reader = file.openSync(mode: FileMode.read);
 
     try {
-      final length = _reader.lengthSync();
-      final List<int> fileHeaderBytes = length > id3FileHeaderLength ? _reader.readSync(id3FileHeaderLength) : [];
+      final length = reader.lengthSync();
+      final List<int> fileHeaderBytes = length > id3FileHeaderLength ? reader.readSync(id3FileHeaderLength) : [];
       // Assume ID3 tag is at beginning of file
       final List<int>? id3FileTag = fileHeaderBytes.length == id3FileHeaderLength ? fileHeaderBytes.sublist(0, 3) : null;
 
       if (id3FileTag != null && latin1.decode(id3FileTag) == 'ID3') {
         final headerBytes = fileHeaderBytes.toList();
         final header = ID3FileHeader.fromHeaderBytes(headerBytes);
 
-        final id3TagBytes = _reader.readSync(header.id3TagSize);
+        final id3TagBytes = reader.readSync(header.id3TagSize);
 
         int initialOffset = 0;
         if (header.hasExtendedHeader) {
@@ -74,7 +74,7 @@ class ID3Parser implements ID3TagReader {
             id3TagBytes: [], initialOffset: 0);
       }
     } finally {
-      _reader.closeSync();
+      reader.closeSync();
     }
   }
 
@@ -139,9 +139,9 @@ class ID3Parser implements ID3TagReader {
     final addParser = (FrameParser parser) => parserMap.addEntries(parser.frameNames.map((e) => MapEntry(e, parser)));
 
     addParser(ChapterFrameParser());
+    addParser(TableOfContentsFrameParser());
     addParser(CommentFrameParser());
     addParser(PictureFrameParser());
-    //addParser(TableOfContentsFrameParser()); // TODO
     addParser(TextInformationFrameParser());
     //addParser(UrlFrameParser()); // TODO
     addParser(UserUrlFrameParser());

lib/src/id3_tag.dart

@@ -4,7 +4,6 @@
 
 import 'extensions/iterable_extension.dart';
 import 'frames/frames.dart';
-import 'frames/chapter_frame.dart';
 
 
 class ID3Tag {
@@ -36,12 +35,29 @@ class ID3Tag {
   Comment? get comment => frameWithTypeAndName<Comment>('COMM');
   List<Comment> get comments => framesWithTypeAndName<Comment>('COMM');
 
-  /// Gets the chapter (`CHAP`) frames, represented as [Chapter] objects. The returned chapters are sorted according to
-  /// start time.
+  /// Gets all the chapter (`CHAP`) frames defined in the tag, represented as [Chapter] objects. The returned chapters
+  /// are sorted according to start time. **NOTE: ** Consider getting chapters via table of contents or by using
+  /// [topLevelChapters].
   List<Chapter> get chapters {
-    final _chapters = framesWithType<Chapter>();
-    _chapters.sort((a, b) => a.startTimeMilliseconds.compareTo(b.startTimeMilliseconds));
-    return _chapters;
+    final chapters = framesWithType<Chapter>();
+    chapters.sort((a, b) => a.startTimeMilliseconds.compareTo(b.startTimeMilliseconds));
+    return chapters;
+  }
+
+  /// Gets the table of contents (`CTOC`) frames, represented as [TableOfContents] objects.
+  List<TableOfContents> get tableOfContents => framesWithType<TableOfContents>();
+  /// Gets the the top level table of contents (`CTOC`) frame or the first one if no top level is found.
+  TableOfContents? get topLevelTOC {
+    final toc = tableOfContents;
+    return toc.firstWhereOrNull((toc) => toc.isTopLevel) ?? toc.firstIfAny();
+  }
+
+  /// Gets all the chapters referenced by the top level table of contents (or the first one). Falls back to [chapters]
+  /// if no table of contents frame is present.
+  List<Chapter> get topLevelChapters {
+    final toc = topLevelTOC;
+    if (toc != null && toc.childElementIds.isNotEmpty) { return chaptersForTOC(toc); }
+    else { return chapters; }
   }
 
   /// Gets the unsynchronized lyric/text transcription ('USLT') frame, represented as a [Lyrics] object.
@@ -82,4 +98,18 @@ class ID3Tag {
   T? frameWithTypeAndName<T extends Frame>(String name) {
     return framesWithTypeAndName<T>(name).firstIfAny();
   }
+
+  /// Gets the chapters matching the element ids in the specified [TableOfContents] object.
+  List<Chapter> chaptersForTOC(TableOfContents toc) {
+    final chapters = framesWithType<Chapter>();
+    List<Chapter> tocChapters = [];
+    for (var elementId in toc.childElementIds) {
+      final index = chapters.indexWhere((c) => c.elementId == elementId);
+      if (index > -1) {
+        tocChapters.add(chapters[index]);
+        chapters.removeAt(index);
+      }
+    }
+    return tocChapters;
+  }
 }

lib/src/raw_frame.dart

@@ -5,6 +5,7 @@
 import 'frames/frame.dart';
 import 'frame_body.dart';
 import 'id3_parser.dart';
+import 'extensions/iterable_extension.dart';
 
 
 class RawFrame {
@@ -28,5 +29,16 @@ class RawFrame {
       frameContent.pos += rawSubFrame.frameSize;
       return id3Parser.parseSubFrame(rawSubFrame);
     }
+    return null;
+  }
+
+  List<Frame> parseSubFrames() {
+    List<Frame> subFrames = [];
+    var pos = 0;
+    do {
+      pos = frameContent.pos;
+      subFrames.addNotNull(parseSubFrame());
+    } while (frameContent.remainingBytes > 0 && frameContent.pos != pos);
+    return subFrames;
   }
 }