{"id":15086032,"url":"https://github.com/krumpetpirate/aaxtomp3","last_synced_at":"2025-10-05T15:31:37.562Z","repository":{"id":38238295,"uuid":"47907764","full_name":"KrumpetPirate/AAXtoMP3","owner":"KrumpetPirate","description":"Convert Audible's .aax filetype to MP3, FLAC, M4A, or OPUS","archived":true,"fork":false,"pushed_at":"2023-03-27T20:09:54.000Z","size":313,"stargazers_count":1186,"open_issues_count":26,"forks_count":166,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-02-12T17:38:14.375Z","etag":null,"topics":["aax","audible","audiobooks","drm","drm-restrictions","ffmpeg","mp3"],"latest_commit_sha":null,"homepage":"https://krumpetpirate.github.io/AAXtoMP3/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KrumpetPirate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-12-13T05:44:34.000Z","updated_at":"2024-02-07T16:56:27.000Z","dependencies_parsed_at":"2023-02-16T00:05:39.728Z","dependency_job_id":"583bf5ba-90f3-4ab7-a516-52a993b26486","html_url":"https://github.com/KrumpetPirate/AAXtoMP3","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KrumpetPirate%2FAAXtoMP3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KrumpetPirate%2FAAXtoMP3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KrumpetPirate%2FAAXtoMP3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KrumpetPirate%2FAAXtoMP3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KrumpetPirate","download_url":"https://codeload.github.com/KrumpetPirate/AAXtoMP3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235411603,"owners_count":18986065,"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":["aax","audible","audiobooks","drm","drm-restrictions","ffmpeg","mp3"],"created_at":"2024-09-25T07:03:56.394Z","updated_at":"2025-10-05T15:31:32.242Z","avatar_url":"https://github.com/KrumpetPirate.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AAXtoMP3\nThe purpose of this software is to convert AAX (or AAXC) files to common MP3, M4A, M4B, flac and ogg formats\nthrough a basic bash script frontend to FFMPEG.\n\nAudible uses the AAX file format to maintain DRM restrictions on their audio\nbooks and if you download your book through your library it will be\nstored in this format.\n\nThe purpose of this software is **not** to circumvent the DRM restrictions\nfor audio books that **you** do not own in that you do not have them on\nyour **personal** Audible account. The purpose of this software is to\ncreate a method for you to download and store your books just in case\nAudible fails for some reason.\n\n## Requirements\n* bash 3.2.57 or later tested\n* ffmpeg version 2.8.3 or later (4.4 or later if the input file is `.aaxc`)\n* libmp3lame - (typically 'lame' in your system's package manager)\n* GNU grep - macOS or BSD users may need to install through package manager\n* GNU sed - see above\n* GNU find - see above\n* jq - only if `--use-audible-cli-data` is set or if converting an .aaxc file\n* mp4art used to add cover art to m4a and m4b files. Optional\n* mediainfo used to add additional media tags like narrator. Optional\n\n## Usage(s)\n```\nbash AAXtoMP3 [-f|--flac] [-o|--opus] [-a|--aac] [-s|--single] [--level \u003cCOMPRESSIONLEVEL\u003e] [-c|--chaptered] [-e:mp3] [-e:m4a] [-e:m4b] [-A|--authcode \u003cAUTHCODE\u003e] [-n|--no-clobber] [-t|--target_dir \u003cPATH\u003e] [-C|--complete_dir \u003cPATH\u003e] [-V|--validate] [--use-audible-cli-data]] [-d|--debug] [-h|--help] [--continue \u003cCHAPTERNUMBER\u003e] \u003cAAX/AAXC INPUT_FILES\u003e...\n```\nor if you want to get guided through the options\n```\nbash interactiveAAXtoMP3 [-a|--advanced] [-h|--help]\n```\n\n* **\u0026lt;AAX INPUT_FILES\u0026gt;**... are considered input file(s), useful for batching!\n\n## Options for AAXtoMP3\n* **-f** or **--flac**   Flac Encoding and as default produces a single file.\n* **-o** or **--opus**   Ogg/Opus Encoding defaults to multiple file output by chapter. The extension is .ogg\n* **-a** or **--aac**    AAC Encoding and produce a m4a single files output.\n* **-A** or **--authcode \u0026lt;AUTHCODE\u0026gt;** for this execution of the command use the provided \u0026lt;AUTHCODE\u0026gt; to decode the AAX file. Not needed if the source file is .aaxc.\n* **-n** or **--no-clobber** If set and the target directory already exists, AAXtoMP3 will exit without overwriting anything.\n* **-t** or **--target_dir \u0026lt;PATH\u0026gt;** change the default output location to the named \u0026lt;PATH\u0026gt;. Note the default location is ./Audiobook of the directory to which each AAX file resides.\n* **-C** or **--complete_dir \u0026lt;PATH\u0026gt;** a directory to place aax files after they have been decoded successfully. Note make a back up of your aax files prior to using this option. Just in case something goes wrong.\n* **-V** or **--validate** Perform 2 validation tests on the supplied aax files. This is more extensive than the normal validation as we attempt to transcode the aax file to a null file.  This can take a long period of time. However it is useful when inspecting a large set of aax files prior to transcoding. As download errors are common with Audible servers.\n* **-e:mp3**         Identical to defaults.\n* **-e:m4a**         Create a m4a audio file. This is identical to --aac\n* **-e:m4b**         Create a m4b audio file. This is the book version of the m4a format.\n* **-s** or **--single**    Output a single file for the entire book. If you only want a single ogg file for instance.\n* **-c** or **--chaptered** Output a single file per chapter. The `--chaptered` will only work if it follows the `--aac -e:m4a -e:m4b --flac` options.\n* **--continue \u0026lt;CHAPTERNUMBER\u0026gt;**      If the splitting into chapters gets interrupted (e.g. by a weak battery on your laptop) you can go on where the process got interrupted. Just delete the last chapter (which was incompletely generated) and redo the task with \"--continue \u0026lt;CHAPTERNUMBER\u0026gt;\" where CHAPTERNUMBER is the chapter that got interrupted.\n* **--level \u0026lt;COMPRESSIONLEVEL\u0026gt;**      Set compression level. May be given for mp3, flac and opus.\n* **--keep-author \u0026lt;FIELD\u0026gt;**           If a book has multiple authors and you don't want all of them in the metadata, with this flag you can specify a specific author (1 is the first, 2 is the second...) to keep while discarding the others.\n* **--author \u0026lt;AUTHOR\u0026gt;**               Manually set the author metadata field, useful if you have multiple books of the same author but the name reported is different (eg. spacing, accents..). Has precedence over `--keep-author`.\n* **-l** or **--loglevel \u0026lt;LOGLEVEL\u0026gt;** Set loglevel: 0 = progress only, 1 (default) = more information, output of chapter splitting progress is limitted to a progressbar, 2 = more information, especially on chapter splitting, 3 = debug mode\n* **--dir-naming-scheme \u0026lt;STRING\u0026gt;** or **-D**      Use a custom directory naming scheme, with variables. See [below](#custom-naming-scheme) for more info.\n* **--file-naming-scheme \u0026lt;STRING\u0026gt;** or **-F**    Use a custom file naming scheme, with variables. See [below](#custom-naming-scheme) for more info.\n* **--chapter-naming-scheme \u0026lt;STRING\u0026gt;**  Use a custom chapter naming scheme, with variables. See [below](#custom-naming-scheme) for more info.\n* **--use-audible-cli-data** Use additional data got with mkb79/audible-cli. See [below](#audible-cli-integration) for more info. Needed for the files in the `aaxc` format.\n* **--audible-cli-library-file** or **-L** Path of the library-file, generated by mkb79/audible-cli (`audible library export -o ./library.tsv`). Only available if `--use-audible-cli-data` is set. This file is required to parse additional metadata such as `$series` or `$series_sequence`.\n* **--ffmpeg-path**  Set the ffmpeg/ffprobe binaries folder. Both of them must be executable and in the same folder.\n* **--ffmpeg-name**  Set a custom name for the ffmpeg binary. Must be executable and in path, or in custom path specified by --ffmpeg-path.\n* **--ffprobe-name**  Set a custom name for the ffprobe binary. Must be executable and in path, or in custom path specified by --ffmpeg-path.\n\n## Options for interactiveAAXtoMP3\n* **-a** or **--advanced** Get more options to choose. Not used right now.\n* **-h** or **--help** Get a help prompt.\nThis script presents you the options you chose last time as default.\nWhen you get asked for the aax-file you may just drag'n'drop it to the terminal.\n\n### AUTHCODE\n**Your** Audible auth code (it won't correctly decode otherwise) (not required to decode the `aaxc` format).\n\n#### Determining your own AUTHCODE\nYou will need your authentication code that comes from Audible's servers. This \nwill be used by ffmpeg to perform the initial audio convert. You can obtain \nthis string from a tool like \n[audible-activator](https://github.com/inAudible-NG/audible-activator) or like [audible-cli](https://github.com/mkb79/audible-cli).\n\n#### Specifying the AUTHCODE.\nIn order of __precidence__.\n1. __--authcode [AUTHCODE]__ The command line option. With the highest precedence.\n2. __.authcode__ If this file is placed in the current working directory and contains only the authcode it is used if the above is not.\n3. __~/.authcode__ a global config file for all the tools. And is used as the default if none of the above are specified.\n__Note:__ At least one of the above must be exist if converting `aax` files. The code must also match the encoding for the user that owns the AAX file(s). If the authcode does not match the AAX file no transcoding will occur.\n\n### MP3 Encoding\n* This is the **default** encoding\n* Produces 1 or more mp3 files for the AAX title.\n* The default mode is **chaptered**\n* If you want a mp3 file per chapter do not use the **--single** option. \n* A m3u playlist file will also be created in this instance in the case of **default** chaptered output.\n* **--level** has to be in range 0-9, where 9 is fastest and 0 is highest quality. Please note: The quality can **never** become higher than the qualitiy of the original aax file!\n\n### Ogg/Opus Encoding\n* Can be done by using the **-o** or **--opus** command line switches\n* The default mode is **chaptered**\n* Opus coded files are stored in the ogg container format for better compatibility.\n* **--level** has to be in range 0-10, where 0 is fastest and 10 is highest quality. Please note: The quality can **never** become higher than the qualitiy of the original aax file!\n\n### AAC Encoding\n* Can be done by using the **-a** or **--aac** command line switches\n* The default mode is **single**\n* Designed to be the successor of the MP3 format\n* Generally achieves better sound quality than MP3 at the same bit rate.\n* This will only produce 1 audio file as output.\n\n### FLAC Encoding\n* Can be done by using the **-f** or **--flac** command line switches\n* The default mode is **single**\n* FLAC is an open format with royalty-free licensing\n* This will only produce 1 audio file as output. If you want a flac file per chapter do use **-c** or **--chaptered**.\n* **--level** has to be in range 0-12, where 0 is fastest and 12 is highest compression. Since flac is lossless, the quality always remains the same.\n\n### M4A and M4B Containers\n* These containers were created by Apple Inc. They were meant to be the successor to mp3.\n* M4A is a container that is meant to hold music and is typically of a higher bitrate.\n* M4B is a container that is meant to hold audiobooks and is typically has bitrates of 64k and 32k.\n* Both formats are chaptered\n* Both support coverart internal\n* The default mode is **single**\n\n### Validating AAX files\n* The **--validate** option will result in only a validation pass over the supplied aax file(s). No transcoding will occur. This is useful when you wish to ensure you have a proper download of your personal Audible audio books. With this option all supplied books are validated.\n* If you do NOT supply the **--validate** option all audio books are still validated when they are processed. However if there is an invalid audio book in the supplied list of books the processing will stop at that point.\n* A third test is performed on the file where the entire file is inspected to see if it is valid. This is a lengthy process. However it will not break the script when an invalid file is found.\n* The 3 test current are:\n    1. aax present\n    1. meta data header in file is valid and complete\n    1. entire file is valid and complete.  _only executed with the **--validate** option._\n\n### Defaults\n* Default out put directory is the base directory of each file listed. Plus the genre, Artist and Title of the Audio Book.\n* The default codec is mp3\n* The default output is by chapter.\n\n### Custom naming scheme\nThe following flags can modify the default naming scheme:\n* **--dir-naming-scheme** or **-D**  \n* **--file-naming-scheme** or **-F** \n* **--chapter-naming-scheme** \n\nEach flag takes a string as argument. If the string contains a variable defined in the script (eg. artist, title, chapter, narrator...), the corresponding value is used.\nThe default options correspond to the following flags:\n* `--dir-naming-scheme '$genre/$artist/$title'`\n* `--file-naming-scheme '$title'`\n* `--chapter-naming-scheme '$title-$(printf %0${#chaptercount}d $chapternum) $chapter'`\n\nAdditional notes:\n* If a command substitution is present in the passed string, (for example `$(printf %0${#chaptercount}d $chapternum)`, used to pad with zeros the chapter number), the commands are executed.\nSo you can use `--dir-naming-scheme '$(date +%Y)/$artist'`, but using `--file-naming-scheme '$(rm -rf /)'` is a really bad idea. Be careful.\n* You can use basic text, like `--dir-naming-scheme 'Converted/$title'`\n* You can also use shell variables as long as you escape them properly: `CustomGenre=Horror ./AAXtoMP3 --dir-naming-scheme \"$CustomGenre/\\$artist/\\$title\" *.aax`\n* If you want shorter chapter names, use `--chapter-naming-scheme '$(printf %0${#chaptercount}d $chapternum) $chapter'`: only chapter number and chapter name\n* If you want to append the narrator name to the title, use `--dir-naming-scheme '$genre/$artist/$title-$narrator' --file-naming-scheme '$title-$narrator'`\n* If you don't want to have the books separated by author, use `--dir-naming-scheme '$genre/$title'`\n* To be able to use `$series` or `$series_sequence` in the schemes the following is required:\n  * `--use-audible-cli-data` is set\n  * you have pre-generated the library-file via `audible library export -o ./library.tsv`\n  * you have set the path to the generated library-file via `--audible-cli-library-file ./library.tsv`\n\n### Installing Dependencies.\nIn general, take a look at [command-not-found.com](https://command-not-found.com/)\n#### FFMPEG,FFPROBE\n__Ubuntu, Linux Mint, Debian__\n```\nsudo apt-get update\nsudo apt-get install ffmpeg libav-tools x264 x265 bc\n```\n\nIn Debian-based system's repositories the ffmpeg version is often outdated. If you want\nto convert .aaxc files, you need at least ffmpeg 4.4. So if your installed version\nneeds to be updated, you can either install a custom repository that has the newer version,\ncompile ffmpeg from source or download pre-compiled binaries.\nYou can then tell AAXtoMP3 to use the compiled binaries with the `--ffmpeg-path` flag.\nYou need to specify the folder where the ffmpeg and ffprobe binaries are. Make sure\nthey are both executable.\n\nIf you have snapd installed, you can also install a recent version of 4.4 from the edge channel:\n```\nsnap install ffmpeg --edge\n```\nIn this case you will need to confiure a custom path _and_ binary name for ffprobe, `--ffmpeg-path /snap/bin/ --ffprobe-name ffmpeg.ffprobe`.\n\n__Fedora__\n\nFedora users need to enable the rpm fusion repository to install ffmpeg. Version 22 and upwards are currently supported. The following command works independent of your current version:\n```\nsudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm\n```\nAfterwards use the package manager to install ffmpeg:\n```\nsudo dnf install ffmpeg\n```\n\n__RHEL or compatible like CentOS__\n\nRHEL version 6 and 7 are currently able to use rpm fusion.\nIn order to use rpm fusion you have to enable EPEL, see http://fedoraproject.org/wiki/EPEL\n\nAdd the rpm fusion repositories in version 6\n```\nsudo yum localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-6.noarch.rpm https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-6.noarch.rpm\n```\nor version 7:\n```\nsudo yum localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-7.noarch.rpm\n```\nthen install ffmpeg:\n```\nsudo yum install ffmpeg\n```\n\n__MacOS__\n```\nbrew install ffmpeg\nbrew install gnu-sed\nbrew install grep\nbrew install findutils\n```\n\n#### mp4art/mp4chaps\n_Note: This is an optional dependency, required for adding cover art to m4a and b4b files only._\n\n__Ubuntu, Linux Mint, Debian__\n```\nsudo apt-get update\nsudo apt-get install mp4v2-utils\n```\n\nOn Debian and Ubuntu the mp4v2-utils package has been deprecated and removed, as the upsteam project is no longer maintained.\nThe package was removed in Debian Buster, and Ubuntu Focal [ 20.04 ].\n\n__CentOS, RHEL \u0026 Fedora__\n```\n# CentOS/RHEL and Fedora users make sure that you have enabled atrpms repository in system. Let’s begin installing FFmpeg as per your operating system.\nyum install mp4v2-utils\n```\n__MacOS__\n```\nbrew install mp4v2\n```\n\n#### mediainfo\n_Note: This is an optional dependency._\n\n__Ubuntu, Linux Mint, Debian__\n```\nsudo apt-get update\nsudo apt-get install mediainfo\n```\n__CentOS, RHEL \u0026 Fedora__\n```\nyum install mediainfo\n```\n__MacOS__\n```\nbrew install mediainfo\n```\n## AAXC files\nThe AAXC format is a new Audible encryption format, meant to replace the old AAX.\nThe encryption has been updated, and now to decrypt the file the authcode\nis not sufficient, we need two \"keys\" which are unique for each audiobook.\nSince getting those keys is not simple, for now the method used to get them\nis handled by the package audible-cli, that stores\nthem in a file when downloading the aaxc file. This means that in order to\ndecrypt the aaxc files, they must be downloaded with audible-cli.\nNote that you need at least [ffmpeg 4.4](#ffmpegffprobe).\n\n## Audible-cli integration\nSome information are not present in the AAX file. For example the chapters's\ntitle, additional chapters division (Opening and End credits, Copyright and\nmore).  Those information are avaiable via a non-public audible API. This\n[repo](https://github.com/mkb79/Audible) provides a python API wrapper, and the\n[audible-cli](https://github.com/mkb79/audible-cli) packege makes easy to get\nmore info. In particular the flags **--cover --cover-size 1215 --chapter**\ndownloads a better-quality cover (.jpg) and detailed chapter infos (.json).\nMore info are avaiable on the package page.\n\nSome books might not be avaiable in the old `aax` format, but only in the newer\n`aaxc` format. In that case, you can use [audible-cli](https://github.com/mkb79/audible-cli)\nto download them. For example, to download all the books in your library in the newer `aaxc` format, as well as\nchapters's title and an HQ cover: `audible download --all --aaxc --cover --cover-size 1215 --chapter`.\n\nTo make AAXtoMP3 use the additional data, specify the **--use-audible-cli-data**\nflag: it expects the cover and the chapter files (and the voucher, if converting\nan aaxc file) to be in the same location of the AAX file.  The naming of these\nfiles must be the one set by audible-cli. When converting aaxc files, the variable\nis automatically set, so be sure to follow the instructions in this paragraph.\n\nFor more information on how to use the `audible-cli` package, check out the git page [audible-cli](https://github.com/mkb79/audible-cli).\n\nPlease note that right now audible-cli is in dev stage, so keep in mind that the\nnaming scheme of the additional files, the flags syntax and other things can\nchange without warning.\n \n\n## Anti-Piracy Notice\nNote that this project **does NOT ‘crack’** the DRM. It simply allows the user to\nuse their own encryption key (fetched from Audible servers) to decrypt the\naudiobook in the same manner that the official audiobook playing software does.\n\nPlease only use this application for gaining full access to your own audiobooks\nfor archiving/conversion/convenience. DeDRMed audiobooks should not be uploaded\nto open servers, torrents, or other methods of mass distribution. No help will\nbe given to people doing such things. Authors, retailers, and publishers all\nneed to make a living, so that they can continue to produce audiobooks for us to\nhear, and enjoy. Don’t be a parasite.\n\nThis blurb is borrowed from the https://apprenticealf.wordpress.com/ page.\n\n## License\nChanged the license to the WTFPL, do whatever you like with this script. Ultimately it's just a front-end for ffmpeg after all.\n\n## Need Help?\nI'll help out if you are having issues, just submit and issue and I'll get back to you when I can.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrumpetpirate%2Faaxtomp3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrumpetpirate%2Faaxtomp3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrumpetpirate%2Faaxtomp3/lists"}