{"id":13961592,"url":"https://github.com/zerolagtime/apple-audiobooks","last_synced_at":"2025-07-21T06:31:08.554Z","repository":{"id":196767701,"uuid":"403461379","full_name":"zerolagtime/apple-audiobooks","owner":"zerolagtime","description":"Convert MP3s to Apple's M4B MPEG-4 audiobook format.  Books are native and recognized as Audiobooks in iTunes and mobile IOS devices.","archived":false,"fork":false,"pushed_at":"2024-07-18T03:00:08.000Z","size":141,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-28T07:34:33.824Z","etag":null,"topics":["audiobook","conversion","docker","linux","mp3","mp4","mpeg"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zerolagtime.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-06T02:26:27.000Z","updated_at":"2024-10-11T02:29:34.000Z","dependencies_parsed_at":"2024-11-28T07:31:12.028Z","dependency_job_id":"783231e5-33c7-4f07-a322-ca66f752c6d4","html_url":"https://github.com/zerolagtime/apple-audiobooks","commit_stats":null,"previous_names":["zerolagtime/apple-audiobooks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zerolagtime/apple-audiobooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerolagtime%2Fapple-audiobooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerolagtime%2Fapple-audiobooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerolagtime%2Fapple-audiobooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerolagtime%2Fapple-audiobooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerolagtime","download_url":"https://codeload.github.com/zerolagtime/apple-audiobooks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerolagtime%2Fapple-audiobooks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266253514,"owners_count":23900051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audiobook","conversion","docker","linux","mp3","mp4","mpeg"],"created_at":"2024-08-08T17:01:17.240Z","updated_at":"2025-07-21T06:31:08.103Z","avatar_url":"https://github.com/zerolagtime.png","language":"Python","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# MP3 to Apple Audiobook Conversion\n\nThis tool converts a collection of MP3 files into a single Apple MP4 audiobook with a `.m4b` extension.  Conversion happens in two stages.  In the first stage, `prepaudiobook` is used to search every source available to figure out metadata, even going out to Google Books if nothing can be found.  The metadata is usually pretty messy or inconsistent and will need to be cleaned up.  Books that are part of a series will also need consistent metadata. \nThe second stage, `mp3tom4b *.mp3` takes the metadata and MP3 files and then converts it to an Apple Audiobook with these features:\n* AAC encoded file with an `.m4b` file extension\n* Recognized by Apple iTunes as an Audiobook, ready to import\n* Cover art\n* Author (Artist)\n* Book Title (Album)\n* Chapter marks (see below)\n* Book description\n* Publication year\n* No copy protection\n* Only one transcoding to reduce noise artifacts\n\n## Installation and Use\nThis software has a lot of external dependencies which can be cumbersome to get installed onto a system.  Therefore, all of the tools have been embedded in a Docker container.  You must have permission to use Docker on your system, be it Linux or Windows.\n\n### Build\nDocker 1.19 or newer must be installed and access to the web must be enabled. \nThe contaier is based upon Ubuntu 18.04 and pulls down source code or \nDeb packages for GPAC and FFMPEG.\nTo build, open a shell window in this folder and type: `./build.sh`.\nA container named audiobook_tools:develop will be created, likely around\n1.2GB in size.\n\n### Linux\nAdd shortcuts and aliases to your shell by sourcing the `host_os.sh` file \nfrom $HOME/.bashrc which adds these commands to your path:\n* **`prepaudiobook`** - examine mp3 files or Overdrive WAX and prepare for conversion\n* **`mp3tom4b`** - convert a prepared folder to Apple's M4B format\n* **`encode`** - a wrapper to mp4tom4b that allows multiple conversion \n  to run at once and not overload your system\n* **`mp4chaps`** - reprocess chapter files without reconverting the book\n* **`multipartEncode`** - split the book into sections\nTest the tools out by typing `source host_os.sh`\n\n## Preparing an Audiobook\nWith all of the MP3 files in a single folder, type `prepaudiobook`.\nThree new files will exist: \n* `info.txt` - a _key_=_value_ file of Audiobook Info\n* `description.txt` - a freeform file that has the book's summary\n* `chapters.txt` - a file that defines chapters to place in the output\nIf the MP3 files came from Overdrive, like with a library, then the\n.wax file will be used to extract more metadata and the chapter data\nembedded as comments in the mp3 files will be used to build the chapter\nfile.  Not all books have good chapter information. No Overdrive books\nhave the year that they were published and you will have to dig this up.\n\nThe description.txt file should be cleaned up for non-ASCII characters.\nThe formal description can be at most 255 characters which can\nbe placed in a `description.short.txt` and still preserve the longer\ndescription.\n\nThe info.txt file has all of the core data to be used.  The following\nkeys must be present:\n* `TITLE`\n* `ARTIST`\n* `ALBUM` (frequently the TITLE, but a book series might use this)\n* `YEAR`\n* `COMMENT` (typically used for the narrator like \"Read by George Guidall\")\n* `OUT` (the output filename with .m4b on the end) \n* (optional) `COVER` (the last image listed will be used)\nSpaces are important in this file.  If no image is used, a default \nicon will be provided.  \n\nThis tool is also interactive.  A Google Books search will be conducted\nand the top 10 books will be chosen.  Review the guessed values\nfrom the MP3 files and if the Google Books search is better, use\none of those - this will include a description and cover image.  \nYou can also press Enter to choose none of the search results.\n\n### Conversion\nConversion is as simple as typing `mp3tom4b`.  If you have several in\na row to convert before you head out for a while, you can use the\nwrapper `encode \u0026` which will load up the machine until it's almost 100%\nbusy and hold of on any other conversions.  Certainly, a more automated\norchestration system could be used, but would overcomplicate an already\ncomplicated process.\n\n`mp3tom4b` will just process the MP3 files in the current folder in\nalphbetical order or you can specify the exact files you want to be\nconverted.  Be careful with your file names.  The `ls -l` command should\nshould show them in the correct order.  You can specify just a glob pattern\nas a parameter in case you have extra MP3s, like from an interview.  \nThe files will be sorted alphabetically before being used.\n\n### Multipart Books\nSome books are very, very long. (I'm looking at you Ron Chernow).  iTunes\nhas historically had difficulty with audiobooks over 12 hours, frequently\nincorrect showing the length as hundreds of hours or more. The output\ncan be split into parts, say three parts, by typing `multipartEncode 3`.\nTo set this up, your `info.txt` should have text that reads `$PART` or\n`${PART}` which will be substituted with the number as appropriate.  Examples:\n* `TITLE=Grant, Part ${PART}`\n* `ALBUM=Grant`\n* `OUT=ron_chernow-grant-part$PART.m4b`\nThe multipart encoder will then make the number of folders, substitute the\npart number, move the MP3 files into their respective subfolder, encode\neach part (`encode \u0026`) and when done, move the MP3 files back up.  It\nis your job to review the m4b's in the subfolder and determine if\nyou like the mix.\nTo choose how many parts, review the `chapters.txt` file and come up with\na divisor that makes sections 12 hours or less.  A 40 hours book might\nget divided up into four parts.\nIf you leave the ALBUM constant as above, then iTunes groups all of the \nparts together which makes it easy to just put one of the sections on\nyour device at a time.\n\n### Chapters\nChapter files must be of the form \"HH:MM:SS.000 Title\", where _Title_\ncan have spaces and other interesting characters.  Chapter files are\nbuilt from the metadata hiding in MP3s from Overdrive books. If there\nis no other guidance, then chapter markers will be built the length\nof each MP3 which is convenient if you get one chapter per MP3 file.\n\n### Metadata\nMetadata in MP3s will be used if available.  You should use a tool\ndedicated to metadata manipulation.  One tools is EasyTAG, although\nthere are others that may be better for this purpose.\n\n## Debugging\nIf you need to view what's going on with an active `encode` session,\nthe output of the internal mp3tom4b is being written to `encode.log`\nwhich you can tail and stay up to date.\n\nIf a conversion seems to have gotten away from you, the easiest solution\nis to issue a `docker kill` on the container you think is responsible.\nThis is a little more tricky if four or six conversions are active.\n\n## LICENSE\nThis work is Copyright 2021 by Charlie Todd \u003czerolagtime@gmail.com\u003e.\nSee the LICENSE for creating your own derivative works.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerolagtime%2Fapple-audiobooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerolagtime%2Fapple-audiobooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerolagtime%2Fapple-audiobooks/lists"}