Skip to main content

PyPI version Docs License Examples

adventuresinodyssey

Unofficial Python clients for the Adventures in Odyssey Club API.

Look up episodes, albums, characters, cast and crew, themes, the radio schedule and search results. With a Club account you can also manage playlists, bookmarks, comments and listening progress.

Installation

pip install adventuresinodyssey

If you plan to log in with ClubClient or AsyncClubClient, also install the browser Playwright uses for login (one-time setup):

playwright install chromium

Requires Python 3.8+.

Which client do I need?

Client Login? Use it for
AIOClient No Anything the public site shows: metadata, promos, radio episodes, search, characters, albums
ClubClient Yes Everything in AIOClient, plus full episodes, playlists, bookmarks, comments, badges and progress
AsyncAIOClient No AIOClient for asyncio code
AsyncClubClient Yes ClubClient for asyncio code

Quick start

No account needed

import random
from adventuresinodyssey import AIOClient

client = AIOClient()

episodes = client.cache_episodes()          # every episode, across all albums
episode = random.choice(episodes)

print(episode["short_name"])                # e.g. "#125: All's Well With Boswell"
print("https://app.adventuresinodyssey.com/content/" + episode["id"])

With a Club account

Keep your credentials out of your code. Put them in a .env file next to your script (and add it to .gitignore):

AIO_EMAIL=you@example.com
AIO_PASSWORD=your_password
AIO_VIEWER_ID=a3J...   # optional, see the ClubClient docs
AIO_PIN=1234           # optional, only if the profile has a PIN

Then load them with python-dotenv (pip install python-dotenv):

import os
from dotenv import load_dotenv
from adventuresinodyssey import ClubClient

load_dotenv()

client = ClubClient(
    email=os.getenv("AIO_EMAIL"),
    password=os.getenv("AIO_PASSWORD"),
    viewer_id=os.getenv("AIO_VIEWER_ID"),
    pin=os.getenv("AIO_PIN"),
)

# Make a playlist out of every season soundtrack
soundtracks = []
collections = client.fetch_content_groupings(grouping_type="Collection", page_size=100)

for group in collections["contentGroupings"]:
    if "Season" in group["name"]:
        soundtracks += [item["id"] for item in group["contentList"]]

playlist = client.create_playlist(name="Soundtracks", content_ids=soundtracks)
playlist_id = playlist["contentGroupings"][0]["id"]
print("https://app.adventuresinodyssey.com/playlists/" + playlist_id)

You don't need to call login(). The client logs in on the first request and saves the session to club_session.json, so later runs skip the browser login. Treat club_session.json like a password: don't commit or share it.

Async

import asyncio
from adventuresinodyssey import AsyncAIOClient

async def main():
    async with AsyncAIOClient() as client:
        radio = await client.fetch_radio(page_size=3)
        for episode in radio["results"]:
            print(episode["relative_air_day"], "-", episode["short_name"])

asyncio.run(main())

Documentation

For streaming episodes, I recommend mpv (pip install mpv for the Python bindings).

Acknowledgements

Thanks to Droopcat for figuring out the Club's authentication flow.

Metadata

Release files for adventuresinodyssey 0.2.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adventuresinodyssey 0.2.6
File Size Uploaded Provenance Actions
adventuresinodyssey-0.2.6.tar.gz 46.7 kB Without provenance Details for adventuresinodyssey-0.2.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adventuresinodyssey 0.2.6
File Interpreter ABI Platform Actions
adventuresinodyssey-0.2.6-py3-none-any.whl Python 3 none any Details for adventuresinodyssey-0.2.6-py3-none-any.whl

Total release size: 94.3 kB

Release files / adventuresinodyssey-0.2.6.tar.gz

Download URL adventuresinodyssey-0.2.6.tar.gz
Size 46.7 kB
Tags Source
SHA-256 checksum
How to use checksums
5968264f807a8c7559bab4589eb78f8d619c2228f9089eeb8d28056b4236795e
BLAKE2b-256 checksum
How to use checksums
4fd289e3a66ccb3bd2cd726c8ab793b0d6de38c3cd64f7e2b446cf19f4f57782
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / adventuresinodyssey-0.2.6-py3-none-any.whl

Download URL adventuresinodyssey-0.2.6-py3-none-any.whl
Size 47.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e8f6d9dcb923855158d0ed4fbf460b558f982421b5ebb53985341f81e59ada7
BLAKE2b-256 checksum
How to use checksums
6c28bcb6f849a120db77adb6d6decafc694846a13e279b39c8820c11f3a14a54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for adventuresinodyssey 0.2.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page