Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

Unreleased

Added

• Optional high-performance crypto backends for significantly improved performance:

  • cryptography (Rust-accelerated, recommended) - install with pip install audible[cryptography]

  • pycryptodome (C-based) - install with pip install audible[pycryptodome]

  • Automatic provider selection: cryptography → pycryptodome → legacy (pure Python fallback)

  • Performance improvements: 5-10x faster AES operations, 10-20x faster RSA operations, 3-5x faster PBKDF2, 5-10x faster hashing

• New audible.crypto_provider module with protocol-based provider abstraction layer:

  • protocols.py - Type-safe Protocol definitions for crypto operations

  • cryptography_provider.py - High-performance implementation using cryptography library

  • pycryptodome_provider.py - High-performance implementation using pycryptodome library

  • legacy_provider.py - Pure-Python implementation wrapper (pyaes, rsa, pbkdf2)

  • registry.py - Provider selection and caching with lazy initialization

• RSA key caching in Authenticator for improved performance on repeated API requests

• Provider override capability: pass crypto_provider parameter to Authenticator.from_file() and related methods

• Process-wide default provider configuration via set_default_crypto_provider()

• Optional high-performance JSON backends for significantly improved JSON serialization performance:

  • orjson (Rust-based, 4-5x faster for compact JSON) - install with pip install audible[orjson]

  • ujson (C-based, 2-3x faster with indent=4 support) - install with pip install audible[ujson]

  • rapidjson (C++ based, 2-3x faster) - install with pip install audible[rapidjson]

  • json-full extra (recommended) - install with pip install audible[json-full] for complete coverage (orjson + ujson)

  • json-fast extra - install with pip install audible[json-fast] for orjson only

  • Automatic provider selection: orjson → ujson → rapidjson → stdlib (pure Python fallback)

  • Performance improvements: 4-5x faster compact JSON (orjson), 2-3x faster pretty-printed JSON (ujson/rapidjson)

  • Smart fallback logic: orjson automatically uses ujson/rapidjson for indent=4

• New audible.json_provider module with protocol-based provider abstraction layer:

  • protocols.py - Type-safe Protocol definition for JSON operations

  • orjson_provider.py - High-performance implementation using orjson library with smart fallback logic

  • ujson_provider.py - High-performance implementation using ujson library

  • rapidjson_provider.py - High-performance implementation using python-rapidjson library

  • stdlib_provider.py - Standard library json wrapper (always available)

  • registry.py - Provider selection and caching with auto-detection

• Process-wide default JSON provider configuration via set_default_json_provider()

Changed

• BREAKING (unreleased modules only): Renamed audible.json module to audible.json_provider to avoid naming conflicts with Python’s built-in json module

• BREAKING (unreleased modules only): Renamed audible.crypto module to audible.crypto_provider for consistency and clarity

  • Note: These modules have not been released yet, so this affects only users testing from the main branch

  • All imports must be updated: from audible.json import → from audible.json_provider import

  • All imports must be updated: from audible.crypto import → from audible.crypto_provider import

• Replaced darglint with pydoclint for docstring validation - modern, actively maintained alternative with better Protocol support

• aescipher.py now uses crypto providers for AES, PBKDF2, and hashing operations

• aescipher.py now uses JSON providers for JSON serialization/deserialization

• auth.py now uses crypto providers for RSA signing operations

• auth.py now uses JSON providers for JSON serialization/deserialization

• login.py now uses JSON providers for JSON serialization

• client.py now uses JSON providers for HTTP response deserialization (replaces httpx’s internal json.loads())

• metadata.py still uses stdlib json directly for separators (edge case)

• Performance optimization: Request parameter lookup now uses frozenset instead of list for O(1) membership testing (previously O(n))

• Performance optimization: Debug logging in client.py now uses lazy evaluation with isEnabledFor(logging.DEBUG) to avoid expensive response text formatting when debug logging is disabled

• Replaced os.urandom with secrets.token_bytes for better cryptographic randomness

• Improved error messages and type annotations throughout crypto layer

• Improved error messages and type annotations throughout JSON layer

• Simplified RSA key loading by removing redundant module-level cache (Authenticator-level caching remains)

• Improved docstring quality across codebase:

  • Added missing return type documentation in Protocol definitions

  • Moved __init__ docstrings to class-level (Google Style Guide compliant)

  • Added explicit type hints for hashmod and mac parameters

  • Fixed argument order mismatches between signatures and docstrings

  • Added missing exception documentation

Fixed

• Prevent SHA-1 deprecation warning spam from cryptography library

• Security vulnerabilities in crypto handling

• MyPy typing issues in crypto provider implementations

Documentation

• Added comprehensive installation guide for crypto extras in README and docs

• Added comprehensive installation guide for JSON extras in README

• Added performance benchmarks and provider selection documentation for crypto providers

• Added performance benchmarks and provider selection documentation for JSON providers

• Added version requirement notes (crypto features available in audible >= 0.11.0)

• Added version requirement notes (JSON features available in audible >= 0.11.0)

• Added example scripts for crypto provider usage

• Added example scripts for JSON provider usage (examples/test_json_autodetect.py, examples/test_json_explicit.py)

Bugfix

• Make register() resilient to missing fields in the registration response:

  • Use tokens.get(“store_authentication_cookie”) instead of direct indexing to avoid KeyError when the server does not return this cookie.

  • Only populate website_cookies when the API includes them; previously code assumed presence and could raise errors.

[0.10.0] - 2024-09-26

Bugfix

• Fix autodetect_locale function

Misc

• Drop support for Python 3.8 and 3.9

• Add support for Python 3.12

[0.9.1] - 2023-09-27

Bugfix

• Fix login issues on brazilian marketplace.

• Fix a RecursionError which occurs when checking the length of an Authenticator instance.

[0.9.0] - 2023-09-27

Bugfix

• Multiple fixes for XXTEA encryption/decryption in metadata module.

Added

• Add brazilian marketplace.

• Login function now checks for a verification-code-form tag in login HTML page.

Changes

• Drop support for Python 3.7.

Misc

• First step to refactor code.

• Switch project to poetry.

• Using nox and ruff for tests and linting.

[0.8.2] - 2022-05-25

Changed

• Allow httpx v0.23.x to fix a bug in httpx

[0.8.1] - 2022-04-20

Bugfix

• fix a bug in Client.delete and AsyncClient.delete method

[0.8.0] - 2022-04-11

Added

• full support of pre-Amazon accounts (e.g. refresh access token, deregister device)

• Client and AsynClient now accepts session kwargs which are bypassed to the underlying httpx Client

• a respone_callback can now be set to Client and AsyncClient class to allow custom preparation of response output

• An absolut url (e.g. https://cde-ta-g7g.amazon.com/FionaCDEServiceEngine/sidecar) can now be passed to a client get, post, delete and put method as the path arg. So in most cases the client raw_request method is not needed anymore.

Changed

• rename (and rework) Client._split_kwargs to Client._prepare_params

[0.7.2] - 2022-03-27

Bugfix

• fix a bug in registration url

[0.7.1] - 2022-03-27

Added

• Authenticator.from_dict to instantiate an Authenticator from dict and Authenticator.to_dict to get authentication data as dict

Bugfix

• register a new device with with_username=True results in a server error due to wrong registration domain

[0.7.0] - 2021-10-25

Bugfix

• make sure activation bytes has 8 bytes, otherwise append ‚0‘ in front until 8 bytes are reached

• make sure metadata1 has 8 bytes, otherwise append ‚0‘ in front until 8 bytes are reached

• If installed, use playwright to login with external browser. Please read here how to install playwright. Then use audible.Authenticator.from_login_external(COUNTRY_CODE) for login.

• fix login issues

[0.6.0] - 2021-10-21

Bugfix

• Fix a bug when searching for „resend-approval-link“ in login page

Changed

• switched to auth_code_flow when login (gives an auth code instead of an access token for security purposes)

• Authenticator.from_login and Authenticator.from_login_external now always register a new device

• Authenticator now refreshes access_token (when needed) before deregister the device

• now simulate Audible app version 3.56.2 under iOS version 15.0.0

• login process now auto-detect next request method and url

Misc

• Correct documentation

• Update example download_books_aaxc.py

• Bump httpx to v0.20.*

Remove

• LoginAuthenticator and FileAuthenticator

• Authenticator.register_device, Authenticator.re_login and Authenticator.re_login_external

[0.5.5] - 2021-07-22

Misc

• switch from httpx 0.16.x to 0.18.x

Added

• logging error messages during login

Changed

• extend allowed chars by email check during login

• instead of raising an exception, invalid email will now be logged as warning

Misc

• Add description to the docs, to handling 2FA

[0.5.4] - 2021-02-28

Added

• Provide a custom serial when login

• Login with Audible username instead of Amazon account for US, UK and DE markteplace

Bugfix

• register a device on Australian marketplace

Misc

• Redesign Module documentation

• Rework description of audible-cli package in documentation

[0.5.3] - 2021-01-25

Added

• function activation_bytes.fetch_activation_sign_auth

• Spain marketplace

Changed

• activation_bytes.get_activation_bytes uses the new fetch_activation_sign_auth function, if signing auth method is available. Otherwise activation bytes will be fetched the old way with a player_token.

[0.5.2] - 2021-01-08

Added

• Add initial cookies to login function to prevent captcha requests in most cases.

[0.5.1] - 2021-01-05

Added

• Fetched activation bytes (with extract=True argument) will be stored to activation_bytes attribute of Authenticator class instance for now. Ignore existing activation bytes and force refresh with auth.get_activation_bytes(force_refresh=True)

• activation_bytes will be loaded from and save to file. Saved auth files are not backward compatible to previous audible versions so keep old files save.

• Add Client.raw_request and AsyncClient.raw_request method.

• Provide a custom Callback with approval_callback keyword argument when login.

• Add classmethod Authenticator.from_login_external and method Authenticator.re_login_external.

• Add login_external function to login.py

Misc

• Add description how to use pyotp with custom otp callback to docs

• Add description how to use login external to docs

[0.5.0] - 2020-12-07

Added

• Added support to output the whole activation blob instead of the extracted activation bytes with get_activation_bytes(extract=False, ...).

• Added support to fetch website cookies for another country with Authenticator.set_website_cookies_for_country.

• Added Client.put and AsyncClient.put.

• Added support to solve approval alerts during login

Changed

• The FileAuthenticator has been deprecated, use classmethod Authenticator.from_file instead.

• The Authenticator don’t inherit from MutableMapping anymore

• The Authenticator sets allowed instance attributes at creation to None, not allowed attributes will raise an Exception

• The LoginAuthenticator has been deprecated, use classmethod Authenticator.from_login instead.

• Changed internal code base for encryption and decryption metadata. Moved the related code to metadata.py.

Remove

• deprecated AudibleAPI

Misc

• Added more docstrings and type hints to code base

• Added support to install Sphinx documentation dependencies with pip install audible[docs].

• Added a guide to use authentication with Postman.

• Rework documentation.

• Added .readthedocs.yml config file

• Added module description (autodoc) to docs

• Uses httpx 0.16.* for now

[0.4.4] - 2020-10-25

Bugfix

• Set padding=„none“ when decrypting license voucher