# sigma67/ytmusicapi architecture

> Architecture diagram of the GitHub repository sigma67/ytmusicapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigma67/ytmusicapi
- Repository: https://github.com/sigma67/ytmusicapi

## Overview

1. **Overall shape**
   - This repository is a **Python 3.10+ client library** for the unofficial YouTube Music API.
   - It does not host a server or UI; the main runtime boundary is **your Python application → this library → YouTube Music web endpoints**.

2. **Primary entry point**
   - The public API is centered on `ytmusicapi.YTMusic` in `ytmusicapi/ytmusic.py`.
   - `YTMusic` acts as the facade that exposes user-facing operations such as search, playlists, library access, uploads, podcasts, charts, browsing, and watch-related requests.

3. **Feature decomposition by mixins**
   - Most user-facing behavior is split across mixins in `ytmusicapi/mixins/`:
     - `browsing.py`, `search.py`, `explore.py`, `playlists.py`, `library.py`, `podcasts.py`, `uploads.py`, `watch.py`, `charts.py`
   - This means the API surface is organized by feature area, while `YTMusic` composes those capabilities into one class.

4. **Request/response flow**
   - Calls generally flow from `YTMusic` into a mixin method, which constructs a request to YouTube Music and then sends the response into parser code.
   - The library appears structured around **request assembly + response normalization**, rather than exposing raw HTTP payloads to callers.

5. **Parsing and data normalization layer**
   - `ytmusicapi/parsers/` contains the response-shaping logic for each domain area:
     - albums, artists, browsing, explore, library, playlists, podcasts, search, songs, uploads, watch
   - These parsers convert YouTube Music’s nested JSON into stable Python dictionaries / structured results that the public API returns.

6. **Shared internal helpers and navigation**
   - Shared logic lives in `helpers.py`, `continuations.py`, and `navigation.py`.
   - These modules likely handle common concerns such as pagination/continuation tokens, response traversal, and general utility transformations that multiple feature areas depend on.

7. **Authentication boundary**
   - Authentication is isolated under `ytmusicapi/auth/`.
   - The repo supports two auth paths:
     - **Browser/header-based auth** via `browser.py` and `auth_parse.py`
     - **OAuth-based auth** via `auth/oauth/` with token, credentials, exception, and model support
   - The README emphasizes emulating the YouTube Music web client using user-provided cookies or OAuth data.

8. **Data model and typed surface**
   - `ytmusicapi/models/` contains typed content helpers such as `TextRun` and lyrics-related models.
   - The repository includes `py.typed`, indicating it is intended to be consumed with static type checking support.

9. **Internationalization/localization**
   - `ytmusicapi/locales/` contains compiled and source translation catalogs for many languages.
   - This is relevant to architecture because response parsing and text handling are designed to work across localized YouTube Music payloads, not just English content.

10. **Public constants, enums, and exceptions**
    - `constants.py`, `enums.py`, `exceptions.py`, and `type_alias.py` define the library’s shared contract surface.
    - These modules standardize API inputs/outputs and error handling across the feature mixins and parsers.

11. **Testing architecture**
    - Tests are organized by subsystem:
      - auth tests, mixin tests, top-level API tests, and setup tests
    - `tests/data/` contains captured JSON fixtures and expected outputs, showing that the library’s correctness is validated primarily through **recorded YouTube Music responses** and parser output comparisons.
    - Header samples for Chrome/Firefox indicate browser-auth parsing is tested against real browser-derived data.

12. **Documentation and onboarding**
    - `docs/` is a full Sphinx documentation site, with reference pages aligned to the same feature breakdown as the codebase.
    - This mirrors the architecture: setup/auth, browsing, library, playlists, podcasts, search, uploads, watch, and explore each have dedicated docs sections.

13. **Packaging, CI, and release flow**
    - The project is packaged with `pyproject.toml` and managed with **PDM** (`pdm.lock` plus GitHub Actions workflows).
    - CI covers linting, coverage, and publishing, which suggests a mature library release pipeline rather than an application deployment pipeline.

14. **What to diagram**
    - A good architecture diagram should show:
      - **Caller application**
      - **`YTMusic` facade**
      - **Feature mixins**
      - **Auth providers**
      - **Request/response parsing layer**
      - **Shared continuation/navigation helpers**
      - **YouTube Music web API**
      - plus optional cross-cutting boxes for **localization**, **typed models**, and **test fixture-driven validation**

Main entry points: [`ytmusicapi/ytmusic.py`](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/ytmusic.py) (YTMusic), [`ytmusicapi/parsers`](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/parsers) (Parsers), [`ytmusicapi/mixins`](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/mixins) (Feature mixins), [`tests`](https://github.com/sigma67/ytmusicapi/tree/main/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core API"]
  node_caller(("Caller app<br/>client"))
  node_ytmusic["YTMusic<br/>facade<br/>[ytmusic.py]"]
  node_mixins["Feature mixins<br/>feature layer"]
  node_browsing["Browsing<br/>mixin<br/>[browsing.py]"]
  node_search["Search<br/>mixin<br/>[search.py]"]
  node_playlists["Playlists<br/>mixin<br/>[playlists.py]"]
  node_library["Library<br/>mixin<br/>[library.py]"]
  node_uploads["Uploads<br/>mixin<br/>[uploads.py]"]
  node_watch["Watch<br/>mixin<br/>[watch.py]"]
  node_charts["Charts<br/>mixin<br/>[charts.py]"]
  node_parsers["Parsers<br/>response normalization"]
  node_helpers["Helpers<br/>shared utils<br/>[helpers.py]"]
  node_continuations["Continuations<br/>pagination<br/>[continuations.py]"]
  node_navigation["Navigation<br/>response traversal<br/>[navigation.py]"]
end

subgraph group_auth["Authentication"]
  node_browser_auth["Browser auth<br/>auth provider<br/>[browser.py]"]
  node_oauth_auth["OAuth auth<br/>auth provider"]
end

subgraph group_support["Support"]
  node_models["Typed models<br/>data models"]
  node_locales["Locales<br/>i18n"]
  node_contracts["Contracts<br/>constants/types<br/>[constants.py]"]
end

subgraph group_quality["Quality & Docs"]
  node_tests["Tests<br/>validation"]
  node_docs["Docs<br/>documentation"]
end

node_youtube[("YouTube Music<br/>external service")]

node_caller -->|"uses"| node_ytmusic
node_ytmusic -->|"composes"| node_mixins
node_mixins -->|"includes"| node_browsing
node_mixins -->|"includes"| node_search
node_mixins -->|"includes"| node_playlists
node_mixins -->|"includes"| node_library
node_mixins -->|"includes"| node_uploads
node_mixins -->|"includes"| node_watch
node_mixins -->|"includes"| node_charts
node_browsing -->|"normalizes with"| node_parsers
node_search -->|"normalizes with"| node_parsers
node_playlists -->|"normalizes with"| node_parsers
node_library -->|"normalizes with"| node_parsers
node_uploads -->|"normalizes with"| node_parsers
node_watch -->|"normalizes with"| node_parsers
node_charts -->|"normalizes with"| node_parsers
node_ytmusic -->|"shares"| node_helpers
node_ytmusic -->|"shares"| node_continuations
node_ytmusic -->|"shares"| node_navigation
node_ytmusic -->|"depends on"| node_contracts
node_ytmusic -->|"auth via"| node_browser_auth
node_ytmusic -->|"auth via"| node_oauth_auth
node_parsers -->|"emits"| node_models
node_parsers -->|"adapts to"| node_locales
node_browser_auth -->|"authenticates to"| node_youtube
node_oauth_auth -->|"authenticates to"| node_youtube
node_browsing -->|"requests"| node_youtube
node_search -->|"requests"| node_youtube
node_playlists -->|"requests"| node_youtube
node_library -->|"requests"| node_youtube
node_uploads -->|"requests"| node_youtube
node_watch -->|"requests"| node_youtube
node_charts -->|"requests"| node_youtube
node_tests -->|"covers"| node_browser_auth
node_tests -->|"covers"| node_oauth_auth
node_tests -->|"fixtures validate"| node_parsers
node_tests -->|"covers"| node_ytmusic
node_docs -->|"documents"| node_ytmusic
node_docs -->|"documents"| node_browser_auth
node_docs -->|"documents"| node_oauth_auth

click node_ytmusic "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/ytmusic.py"
click node_mixins "https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/mixins"
click node_browsing "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/browsing.py"
click node_search "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/search.py"
click node_playlists "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/playlists.py"
click node_library "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/library.py"
click node_uploads "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/uploads.py"
click node_watch "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/watch.py"
click node_charts "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/charts.py"
click node_parsers "https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/parsers"
click node_helpers "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/helpers.py"
click node_continuations "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/continuations.py"
click node_navigation "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/navigation.py"
click node_browser_auth "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/auth/browser.py"
click node_oauth_auth "https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/auth/oauth"
click node_models "https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/models"
click node_locales "https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/locales"
click node_contracts "https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/constants.py"
click node_tests "https://github.com/sigma67/ytmusicapi/tree/main/tests"
click node_docs "https://github.com/sigma67/ytmusicapi/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_caller,node_ytmusic,node_mixins,node_browsing,node_search,node_playlists,node_library,node_uploads,node_watch,node_charts,node_parsers,node_helpers,node_continuations,node_navigation toneBlue
class node_browser_auth,node_oauth_auth toneAmber
class node_models,node_locales,node_contracts toneMint
class node_tests,node_docs toneRose
class node_youtube toneNeutral
```

## Components

### Core API

Public facade, feature mixins, parsing, and shared helpers.

- **Caller app**: client · Python application that uses the library.
- [YTMusic](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/ytmusic.py): facade · Primary public API entry point. · `ytmusicapi/ytmusic.py`
- [Feature mixins](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/mixins): feature layer · Composable user-facing capabilities split by domain. · `ytmusicapi/mixins`
- [Browsing](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/browsing.py): mixin · Browse and navigation operations. · `ytmusicapi/mixins/browsing.py`
- [Search](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/search.py): mixin · Search operations and result assembly. · `ytmusicapi/mixins/search.py`
- [Playlists](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/playlists.py): mixin · Playlist CRUD and playlist views. · `ytmusicapi/mixins/playlists.py`
- [Library](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/library.py): mixin · Library browsing and saved content. · `ytmusicapi/mixins/library.py`
- [Uploads](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/uploads.py): mixin · User upload browsing and related requests. · `ytmusicapi/mixins/uploads.py`
- [Watch](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/watch.py): mixin · Track and playback-related watch requests. · `ytmusicapi/mixins/watch.py`
- [Charts](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/mixins/charts.py): mixin · Chart and trending playlist access. · `ytmusicapi/mixins/charts.py`
- [Parsers](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/parsers): response normalization · Convert YouTube Music JSON into stable library outputs. · `ytmusicapi/parsers`
- [Helpers](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/helpers.py): shared utils · Common utilities for requests and transformations. · `ytmusicapi/helpers.py`
- [Continuations](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/continuations.py): pagination · Continuation token and pagination handling. · `ytmusicapi/continuations.py`
- [Navigation](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/navigation.py): response traversal · Traversal helpers for nested YouTube Music payloads. · `ytmusicapi/navigation.py`

### Authentication

Browser/header auth and OAuth token handling.

- [Browser auth](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/auth/browser.py): auth provider · Header and cookie based authentication parsing. · `ytmusicapi/auth/browser.py`
- [OAuth auth](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/auth/oauth): auth provider · OAuth token, credentials, and model handling. · `ytmusicapi/auth/oauth`

### Support

Typed models, localization, and shared contracts.

- [Typed models](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/models): data models · Typed content helpers such as text runs and lyrics. · `ytmusicapi/models`
- [Locales](https://github.com/sigma67/ytmusicapi/tree/main/ytmusicapi/locales): i18n · Compiled translations for localized payload handling. · `ytmusicapi/locales`
- [Contracts](https://github.com/sigma67/ytmusicapi/blob/main/ytmusicapi/constants.py): constants/types · Enums, constants, aliases, and exceptions shared across the API. · `ytmusicapi/constants.py`

### Quality & Docs

Tests and documentation that validate the library.

- [Tests](https://github.com/sigma67/ytmusicapi/tree/main/tests): validation · Recorded-response and unit coverage for auth and feature layers. · `tests`
- [Docs](https://github.com/sigma67/ytmusicapi/tree/main/docs): documentation · Sphinx reference and setup guides mirroring the API surface. · `docs`

### Other components

- **YouTube Music**: external service · Unofficial web endpoints consumed by the client library.

## Connections

- Caller app → YTMusic: uses · Application code instantiates and calls the public facade.
- YTMusic → Feature mixins: composes · Facade behavior is assembled from domain-specific mixins.
- Feature mixins → Browsing: includes · Browsing capability.
- Feature mixins → Search: includes · Search capability.
- Feature mixins → Playlists: includes · Playlist capability.
- Feature mixins → Library: includes · Library capability.
- Feature mixins → Uploads: includes · Uploads capability.
- Feature mixins → Watch: includes · Watch capability.
- Feature mixins → Charts: includes · Charts capability.
- Browsing → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Search → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Playlists → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Library → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Uploads → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Watch → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- Charts → Parsers: normalizes with · Feature methods delegate response shaping to parsers.
- YTMusic → Helpers: shares · Facade and mixins rely on shared utility logic.
- YTMusic → Continuations: shares · Pagination flows use continuation handling.
- YTMusic → Navigation: shares · Nested payload traversal is reused across requests.
- YTMusic → Contracts: depends on · Public API uses shared constants, enums, aliases, and errors.
- YTMusic → Browser auth: auth via · Browser/header authentication path.
- YTMusic → OAuth auth: auth via · OAuth authentication path.
- Parsers → Typed models: emits · Parsing produces typed content structures.
- Parsers → Locales: adapts to · Parsing handles localized content variants.
- Browser auth → YouTube Music: authenticates to · Provides browser-derived headers or cookies for requests.
- OAuth auth → YouTube Music: authenticates to · Exchanges and refreshes OAuth-based access.
- Browsing → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Search → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Playlists → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Library → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Uploads → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Watch → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Charts → YouTube Music: requests · Feature calls hit YouTube Music endpoints.
- Tests → Browser auth: covers · Browser header parsing is validated with recorded samples.
- Tests → OAuth auth: covers · OAuth behavior is validated with auth tests.
- Tests → Parsers: fixtures validate · Recorded JSON fixtures verify response normalization.
- Tests → YTMusic: covers · Top-level API behavior is tested end to end.
- Docs → YTMusic: documents · Reference docs mirror the public facade and feature groups.
- Docs → Browser auth: documents · Setup docs cover browser/header auth.
- Docs → OAuth auth: documents · Setup docs cover OAuth auth.