How can I best format chapter information?

[n8udd]

I have recently downloaded my Audible library using Libation.

For each book I currently have a .mp3, .cue, .m4b and .metadata.json files.

The metadata.json file output is below, but I was wondering what I need to edit beforehand so that the chapters will show the correct chapter names.

Is there any kind of documentation for how BookPlayer parses metadata and perhaps any kind of best practices/standards for formatting?

{
  "asin": "B01IC2ZBMO",
  "asset_details": [],
  "authors": [
    {
      "asin": "B00C7AI3MS",
      "name": "Tom Fletcher"
    }
  ],
  "available_codecs": [
    {
      "enhanced_codec": "format4",
      "format": "Format4",
      "is_kindle_enhanced": false,
      "name": "format4"
    },
    {
      "enhanced_codec": "LC_32_22050_stereo",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "aax_22_32"
    },
    {
      "enhanced_codec": "LC_64_22050_stereo",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "aax_22_64"
    },
    {
      "enhanced_codec": "piff2232",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "piff_22_32"
    },
    {
      "enhanced_codec": "piff2264",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "piff_22_64"
    },
    {
      "enhanced_codec": "mp42264",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "mp4_22_64"
    },
    {
      "enhanced_codec": "mp42232",
      "format": "Enhanced",
      "is_kindle_enhanced": true,
      "name": "mp4_22_32"
    },
    {
      "enhanced_codec": "aax",
      "format": "Enhanced",
      "is_kindle_enhanced": false,
      "name": "aax"
    }
  ],
  "category_ladders": [
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19376663031",
          "name": "Action & Adventure"
        },
        {
          "id": "19376664031",
          "name": "Animals"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19376675031",
          "name": "Animals & Nature"
        },
        {
          "id": "19376676031",
          "name": "Animals"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19376866031",
          "name": "Growing Up & Facts of Life"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19376866031",
          "name": "Growing Up & Facts of Life"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19376994031",
          "name": "Holidays & Celebrations"
        },
        {
          "id": "19377001031",
          "name": "Christmas"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19377033031",
          "name": "Literature & Fiction"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19377033031",
          "name": "Literature & Fiction"
        }
      ],
      "root": "Genres"
    },
    {
      "ladder": [
        {
          "id": "19376662031",
          "name": "Children's Audiobooks"
        },
        {
          "id": "19377033031",
          "name": "Literature & Fiction"
        },
        {
          "id": "19377057031",
          "name": "Humorous Fiction"
        }
      ],
      "root": "Genres"
    }
  ],
  "content_delivery_type": "SinglePartBook",
  "content_type": "Product",
  "customer_reviews": [
    {
      "asin": "B01IC2ZBMO",
      "author_id": "amzn1.account.AF6AEDAKXYBZZWL7HQV7JPQXA54A",
      "author_name": "Amazon Customer",
      "body": "I just can't think of anything negative about this book, it's truly wonderful in every way. I want to listen to it all over again, my new Christmas read for me and my children for many years to come.",
      "format": "Freeform",
      "id": "86e5d866f6504844b72e6e42be8a06f5",
      "location": "",
      "ratings": {
        "overall_rating": 5,
        "performance_rating": 5,
        "story_rating": 5
      },
      "review_content_scores": {
        "content_quality": 94,
        "num_helpful_votes": 15,
        "num_unhelpful_votes": 0
      },
      "submission_date": "2017-11-20T13:56:57Z",
      "title": "AMAZING "
    },
    {
      "asin": "B01IC2ZBMO",
      "author_id": "amzn1.account.AEOTBWTR7TVCQVMEVGACN5PRR4YQ",
      "author_name": "Danny Phillips",
      "body": "[{ \"answer\" : \"As a big fan of Tom Fletcher I was so excited to here about this book and with much anticipation I listened to it. It is not my usual type of book to listen to but it was a must listen as it was... Tom!\", \"type\" : \"Overall\", \"question\" : \"Where does The Christmasaurus rank among all the audiobooks you’ve listened to so far?\", \"id\" : 228, \"typeString\" : \"overall\" }, { \"answer\" : \"I am disabled myself and I loved that the main charater was also disabled... an unusual thing in and of itself!\", \"type\" : \"Story\", \"question\" : \"What did you like best about this story?\", \"id\" : 191, \"typeString\" : \"story\" }, { \"answer\" : \"Father Christmas....sounded just as I would imagine him to...I've not met the real one you see ;)\", \"type\" : \"Performance\", \"question\" : \"Which character – as performed by Paul Shelley – was your favourite?\", \"id\" : 216, \"typeString\" : \"performance\" }, { \"answer\" : \"It certainly pulled on the heart strings!\", \"type\" : \"Genre\", \"question\" : \"Did you have an emotional reaction to this book? Did it make you laugh or cry?\", \"id\" : 246, \"typeString\" : \"genre\" }, { \"answer\" : \"It's not a life changing book but it is a lovely story to escape this world from for a while.<br/><br/>Now....I have booked tickets to go and see the Christmasaurus live with my husband and my nephew and we are all very excited!! :)<br/>\", \"type\" : \"Misc\", \"question\" : \"Any additional comments?\", \"id\" : -1, \"typeString\" : \"misc\" } ]",
      "format": "Guided",
      "guided_responses": [
        {
          "answer": "As a big fan of Tom Fletcher I was so excited to here about this book and with much anticipation I listened to it. It is not my usual type of book to listen to but it was a must listen as it was... Tom!",
          "id": "228",
          "question": "Where does The Christmasaurus rank among all the audiobooks you’ve listened to so far?",
          "question_type": "Overall"
        },
        {
          "answer": "I am disabled myself and I loved that the main charater was also disabled... an unusual thing in and of itself!",
          "id": "191",
          "question": "What did you like best about this story?",
          "question_type": "Story"
        },
        {
          "answer": "Father Christmas....sounded just as I would imagine him to...I've not met the real one you see ;)",
          "id": "216",
          "question": "Which character – as performed by Paul Shelley – was your favourite?",
          "question_type": "Performance"
        },
        {
          "answer": "It certainly pulled on the heart strings!",
          "id": "246",
          "question": "Did you have an emotional reaction to this book? Did it make you laugh or cry?",
          "question_type": "Genre"
        },
        {
          "answer": "It's not a life changing book but it is a lovely story to escape this world from for a while.<br/><br/>Now....I have booked tickets to go and see the Christmasaurus live with my husband and my nephew and we are all very excited!! :)<br/>",
          "id": "-1",
          "question": "Any additional comments?",
          "question_type": "Misc"
        }
      ],
      "id": "_SDO5R3OW0QT9",
      "location": "",
      "ratings": {
        "overall_rating": 4,
        "performance_rating": 4,
        "story_rating": 4
      },
      "review_content_scores": {
        "content_quality": 83,
        "num_helpful_votes": 14,
        "num_unhelpful_votes": 2
      },
      "submission_date": "2017-01-25T07:57:39Z",
      "title": "Creative and magical"
    },
    {
      "asin": "B01IC2ZBMO",
      "author_id": "amzn1.account.AHX3BXK2QZ7RDFPVX4P6I325XRXQ",
      "author_name": "Kindle Customer",
      "body": "I think this one will be re listened to my children were the wrong way around for this. My 7yr old daughter loved the Christmas stuff but not a fan of dinosaurs and my 5yr old son loved the dinosaur bits but not old enough to follow the in between bits yet. Meanwhile mummy loved it, the story had a real Roald Dahl feel to the writing and the narrator was brilliant. I would have been tongue twisted if I had been reading the book version and the songs were great. There were some great side topics covered in the story including disability and bullying and it was refreshing to have different family structures to the typically portrayed mum dad and two kids set up. Definately one I'd recommend to 7yrs and over particularly if they love dinosaurs.",
      "format": "Freeform",
      "id": "_APJ3GBGY1LST",
      "location": "",
      "ratings": {
        "overall_rating": 4,
        "performance_rating": 5,
        "story_rating": 4
      },
      "review_content_scores": {
        "content_quality": 88,
        "num_helpful_votes": 14,
        "num_unhelpful_votes": 1
      },
      "submission_date": "2016-11-18T16:22:07Z",
      "title": "Great Christmas story with a Roald Dahl feel to it"
    }
  ],
  "format_type": "unabridged",
  "has_children": false,
  "is_adult_product": false,
  "is_listenable": true,
  "is_purchasability_suppressed": false,
  "is_vvab": false,
  "issue_date": "2016-10-06",
  "language": "english",
  "merchandising_summary": "The Christmasaurus is a story about a boy named William Trundle and a dinosaur, the Christmasaurus. It's about how they meet one Christmas Eve and have a magical adventure....",
  "narrators": [
    {
      "name": "Paul Shelley"
    }
  ],
  "plans": [],
  "price": {
    "credit_price": 1.0,
    "list_price": {
      "base": 10.989999771118164,
      "currency_code": "GBP",
      "merchant_id": "A2YHV2RYTDNFG3",
      "type": "list"
    },
    "lowest_price": {
      "base": 7.989999771118164,
      "currency_code": "GBP",
      "merchant_id": "A2YHV2RYTDNFG3",
      "type": "member"
    },
    "ws4v_upsell_price": {
      "base": 3.4700000286102295,
      "currency_code": "GBP",
      "merchant_id": "A2YHV2RYTDNFG3",
      "type": "ws4v_upsell"
    }
  },
  "product_images": {
    "500": "https://m.media-amazon.com/images/I/51O6vCjr-7L._SL500_.jpg"
  },
  "publication_datetime": "2016-10-06T07:00:00Z",
  "publisher_name": "Penguin Audio",
  "publisher_summary": "<p><i>The Christmasaurus</i> is a story about a boy named William Trundle and a dinosaur, the Christmasaurus. It's about how they meet one Christmas Eve and have a magical adventure. </p> <p>It's about friendship and families, sleigh bells and Santa, singing elves and flying reindeer, music and magic. It's about discovering your heart's true desire and learning that the impossible might just be possible.... </p>",
  "rating": {
    "num_reviews": 89,
    "overall_distribution": {
      "average_rating": 4.67984693877551,
      "display_average_rating": "4.7",
      "display_stars": 4.5,
      "num_five_star_ratings": 632,
      "num_four_star_ratings": 90,
      "num_one_star_ratings": 17,
      "num_ratings": 784,
      "num_three_star_ratings": 42,
      "num_two_star_ratings": 3
    },
    "performance_distribution": {
      "average_rating": 4.690402476780186,
      "display_average_rating": "4.7",
      "display_stars": 4.5,
      "num_five_star_ratings": 509,
      "num_four_star_ratings": 97,
      "num_one_star_ratings": 7,
      "num_ratings": 646,
      "num_three_star_ratings": 24,
      "num_two_star_ratings": 9
    },
    "story_distribution": {
      "average_rating": 4.670261941448382,
      "display_average_rating": "4.7",
      "display_stars": 4.5,
      "num_five_star_ratings": 505,
      "num_four_star_ratings": 98,
      "num_one_star_ratings": 9,
      "num_ratings": 649,
      "num_three_star_ratings": 31,
      "num_two_star_ratings": 6
    }
  },
  "reasons_for_reporting_review": [
    {
      "reported_reason_string_id": "adbl_review_reported_reason_csam",
      "reported_reason_value": "csam"
    },
    {
      "reported_reason_string_id": "adbl_review_reported_reason_discriminatory_content",
      "reported_reason_value": "discriminatory_content"
    },
    {
      "reported_reason_string_id": "adbl_review_reported_reason_hate_speech",
      "reported_reason_value": "hate_speech"
    },
    {
      "reported_reason_string_id": "adbl_review_reported_reason_inappropriate_content",
      "reported_reason_value": "inappropriate_content"
    },
    {
      "reported_reason_string_id": "adbl_review_reported_reason_ip_infringement",
      "reported_reason_value": "ip_infringement"
    },
    {
      "reported_reason_string_id": "adbl_review_reported_reason_other_concerning_content",
      "reported_reason_value": "other_concerning_content"
    }
  ],
  "relationships": [
    {
      "asin": "B07NPXW3SS",
      "content_delivery_type": "BookSeries",
      "relationship_to_product": "parent",
      "relationship_type": "series",
      "sequence": "1",
      "sku": "SE_RIES_037048UK",
      "sku_lite": "SE_RIES_037048",
      "sort": "1",
      "title": "The Christmasaurus",
      "url": "/pd/The-Christmasaurus-Audiobook/B07NPXW3SS"
    }
  ],
  "release_date": "2016-10-06",
  "runtime_length_min": 338,
  "sample_url": "https://samples.audible.co.uk/bk/pauk/000800/bk_pauk_000800_sample.mp3",
  "series": [
    {
      "asin": "B07NPXW3SS",
      "sequence": "1",
      "title": "The Christmasaurus",
      "url": "/pd/The-Christmasaurus-Audiobook/B07NPXW3SS"
    }
  ],
  "sku": "BK_PAUK_000800UK",
  "sku_lite": "BK_PAUK_000800",
  "social_media_images": {
    "facebook": "https://m.media-amazon.com/images/I/51O6vCjr-7L._SL10_UR1600,800_CR200,50,1200,630_CLa%7C1200,630%7C51O6vCjr-7L.jpg%7C0,0,1200,630+82,82,465,465_PJAdblSocialShare-Gradientoverlay-largeasin-0to70,TopLeft,0,0_PJAdblSocialShare-AudibleLogo-Large,TopLeft,600,270_OU01_ZBLISTENING%20ON,617,216,52,500,AudibleSansMd,30,255,255,255.jpg",
    "twitter": "https://m.media-amazon.com/images/I/51O6vCjr-7L._SL10_UR1600,800_CR200,50,1024,512_CLa%7C1024,512%7C51O6vCjr-7L.jpg%7C0,0,1024,512+67,67,376,376_PJAdblSocialShare-Gradientoverlay-twitter-largeasin-0to60,TopLeft,0,0_PJAdblSocialShare-AudibleLogo-Medium,TopLeft,490,223_OU01_ZBLISTENING%20ON,483,152,55,450,AudibleSansMd,32,255,255,255.jpg"
  },
  "thesaurus_subject_keywords": [
    "la_confidential",
    "literature-and-fiction"
  ],
  "title": "The Christmasaurus",
  "ChapterInfo": {
    "brandIntroDurationMs": 1533,
    "brandOutroDurationMs": 3204,
    "chapters": [
      {
        "chapters": null,
        "length_ms": 567496,
        "start_offset_ms": 0,
        "start_offset_sec": 0,
        "title": "Chapter 1"
      },
      {
        "chapters": null,
        "length_ms": 753023,
        "start_offset_ms": 567496,
        "start_offset_sec": 567,
        "title": "Chapter 2"
      },
      {
        "chapters": null,
        "length_ms": 568564,
        "start_offset_ms": 1320519,
        "start_offset_sec": 1321,
        "title": "Chapter 3"
      },
      {
        "chapters": null,
        "length_ms": 548409,
        "start_offset_ms": 1889083,
        "start_offset_sec": 1889,
        "title": "Chapter 4"
      },
      {
        "chapters": null,
        "length_ms": 488873,
        "start_offset_ms": 2437492,
        "start_offset_sec": 2437,
        "title": "Chapter 5"
      },
      {
        "chapters": null,
        "length_ms": 447727,
        "start_offset_ms": 2926365,
        "start_offset_sec": 2926,
        "title": "Chapter 6"
      },
      {
        "chapters": null,
        "length_ms": 484740,
        "start_offset_ms": 3374092,
        "start_offset_sec": 3374,
        "title": "Chapter 7"
      },
      {
        "chapters": null,
        "length_ms": 487758,
        "start_offset_ms": 3858832,
        "start_offset_sec": 3859,
        "title": "Chapter 8"
      },
      {
        "chapters": null,
        "length_ms": 667899,
        "start_offset_ms": 4346590,
        "start_offset_sec": 4347,
        "title": "Chapter 9"
      },
      {
        "chapters": null,
        "length_ms": 375885,
        "start_offset_ms": 5014489,
        "start_offset_sec": 5014,
        "title": "Chapter 10"
      },
      {
        "chapters": null,
        "length_ms": 779494,
        "start_offset_ms": 5390374,
        "start_offset_sec": 5390,
        "title": "Chapter 11"
      },
      {
        "chapters": null,
        "length_ms": 875857,
        "start_offset_ms": 6169868,
        "start_offset_sec": 6170,
        "title": "Chapter 12"
      },
      {
        "chapters": null,
        "length_ms": 702636,
        "start_offset_ms": 7045725,
        "start_offset_sec": 7046,
        "title": "Chapter 13"
      },
      {
        "chapters": null,
        "length_ms": 470854,
        "start_offset_ms": 7748361,
        "start_offset_sec": 7748,
        "title": "Chapter 14"
      },
      {
        "chapters": null,
        "length_ms": 635391,
        "start_offset_ms": 8219215,
        "start_offset_sec": 8219,
        "title": "Chapter 15"
      },
      {
        "chapters": null,
        "length_ms": 688936,
        "start_offset_ms": 8854606,
        "start_offset_sec": 8855,
        "title": "Chapter 16"
      },
      {
        "chapters": null,
        "length_ms": 645097,
        "start_offset_ms": 9543542,
        "start_offset_sec": 9544,
        "title": "Chapter 17"
      },
      {
        "chapters": null,
        "length_ms": 449120,
        "start_offset_ms": 10188639,
        "start_offset_sec": 10189,
        "title": "Chapter 18"
      },
      {
        "chapters": null,
        "length_ms": 533548,
        "start_offset_ms": 10637759,
        "start_offset_sec": 10638,
        "title": "Chapter 19"
      },
      {
        "chapters": null,
        "length_ms": 711413,
        "start_offset_ms": 11171307,
        "start_offset_sec": 11171,
        "title": "Chapter 20"
      },
      {
        "chapters": null,
        "length_ms": 674307,
        "start_offset_ms": 11882720,
        "start_offset_sec": 11883,
        "title": "Chapter 21"
      },
      {
        "chapters": null,
        "length_ms": 153066,
        "start_offset_ms": 12557027,
        "start_offset_sec": 12557,
        "title": "Chapter 22"
      },
      {
        "chapters": null,
        "length_ms": 514554,
        "start_offset_ms": 12710093,
        "start_offset_sec": 12710,
        "title": "Chapter 23"
      },
      {
        "chapters": null,
        "length_ms": 950764,
        "start_offset_ms": 13224647,
        "start_offset_sec": 13225,
        "title": "Chapter 24"
      },
      {
        "chapters": null,
        "length_ms": 439089,
        "start_offset_ms": 14175411,
        "start_offset_sec": 14175,
        "title": "Chapter 25"
      },
      {
        "chapters": null,
        "length_ms": 669292,
        "start_offset_ms": 14614500,
        "start_offset_sec": 14615,
        "title": "Chapter 26"
      },
      {
        "chapters": null,
        "length_ms": 674075,
        "start_offset_ms": 15283792,
        "start_offset_sec": 15284,
        "title": "Chapter 27"
      },
      {
        "chapters": null,
        "length_ms": 399337,
        "start_offset_ms": 15957867,
        "start_offset_sec": 15958,
        "title": "Chapter 28"
      },
      {
        "chapters": null,
        "length_ms": 1194156,
        "start_offset_ms": 16357204,
        "start_offset_sec": 16357,
        "title": "Chapter 29"
      },
      {
        "chapters": null,
        "length_ms": 515669,
        "start_offset_ms": 17551360,
        "start_offset_sec": 17551,
        "title": "Chapter 30"
      },
      {
        "chapters": null,
        "length_ms": 469322,
        "start_offset_ms": 18067029,
        "start_offset_sec": 18067,
        "title": "Chapter 31"
      },
      {
        "chapters": null,
        "length_ms": 584586,
        "start_offset_ms": 18536351,
        "start_offset_sec": 18536,
        "title": "Chapter 32"
      },
      {
        "chapters": null,
        "length_ms": 352618,
        "start_offset_ms": 19120937,
        "start_offset_sec": 19121,
        "title": "Chapter 33"
      },
      {
        "chapters": null,
        "length_ms": 869448,
        "start_offset_ms": 19473555,
        "start_offset_sec": 19474,
        "title": "Chapter 34"
      }
    ],
    "is_accurate": true,
    "runtime_length_ms": 20343003,
    "runtime_length_sec": 20343
  },
  "ContentReference": {
    "acr": "CR!VT7YK26V0D04FEPFWBMRN011QNGZ",
    "asin": "B01IC2ZBMO",
    "codec": "mp4a.40.2",
    "content_format": "AAX_22_64",
    "content_size_in_bytes": 164514637,
    "file_version": "1",
    "marketplace": "A2I9A3Q2GNFNGQ",
    "sku": "BK_PAUK_000800",
    "tempo": "1.0",
    "version": "297681"
  }
}

[n8udd]

FWIW, I'm a PHP dev that is currently learning SwiftUI (100 days of swift) and would love to be able to contribute to this project at some point!

If you have any good-first-issue tasks, I'd be keen to look over them and see if I can help at all.

[GianniCarlo]

Regarding good first tasks for SwiftUI, 🤔 I've been thinking about reworking the current sleep timer selection UI, so instead of the list of options, we show a drawer (like with the speed controls), where we would be able to activate/turn off sleep timer, and also toggle the shake to snooze feature, and possibly add a toggle for a sticky sleep timer. I don't have a definitive UI in mind though, so probably not the best place to start on, as it could take some iterations until the UI is defined 🤔. I'll try to think about something else where SwiftUI could be used too though

[GianniCarlo]

Hi @n8udd ! usually the m4b files from Audible already have the chapters info encoded in, could you try importing that file into the app and see if the chapters are properly rendered? as to how BookPlayer parses this metadata, the AVFoundation framework provided by Apple is sort of a black box that handles extracting the metadata and exposes them via a separate API, but, for mp3s, we have verified that if you follow the ID3 tags standard(?) where besides the chapters (CHAP) array, you need to provide a table of contents (CTOC) frame, where it details the order of the chapters. Re the mp4 container, I haven't looked too much into it to be honest, but hopefully the m4b file already has all that info available

As an additional note, if you download the books from your Audible library (aax format), there's an open source project, that handle removing the DRM, and even have the website up, where you just drop the aax file, select output format and OS, and it'll put out the file free of DRM and with all the metadata in place (I've only tested with m4b format)