# yangpz005/mpv-to-bgm architecture

> Architecture diagram of the GitHub repository yangpz005/mpv-to-bgm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yangpz005/mpv-to-bgm
- Repository: https://github.com/yangpz005/mpv-to-bgm

## Overview

mpv-to-bgm synchronizes anime playback with a user’s Bangumi watched-episode list. The principal workflow starts with a playback file and progress, filters below-threshold or ignored files, parses title/season/episode, resolves a Bangumi subject through manual mappings, aliases, cache, Bangumi search, and AniList fallback, then finds the episode and marks it watched. The graph also includes CLI mapping and OAuth setup. The README documents the mpv integration and matching capabilities; some wiring details for the Lua plugin and unsampled matching stages are therefore shown only where documentation supports them.

Main entry points: [`scripts/mpv-to-bgm/src/main.py`](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/main.py) (Sync and CLI), [`scripts/mpv-to-bgm/src/mapper.py`](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/mapper.py) (Title mapper), [`scripts/mpv-to-bgm/src/bgm_client.py`](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/bgm_client.py) (Bangumi client), [`scripts/mpv-to-bgm/src/config.py`](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/config.py) (Config manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Playback intake"]
  node_mpv_script["mpv Lua plugin<br/>[main.lua]"]
  node_sync_entry["Sync and CLI<br/>[main.py]"]
  node_filename_parser["Filename parser<br/>[parser.py]"]
end

subgraph group_matching["Title matching"]
  node_mapper["Title mapper<br/>[mapper.py]"]
  node_mapping_files["Mappings and aliases"]
  node_cache_db[("Mapping and sync cache<br/>[mapper.py]")]
  node_anilist_client["AniList client<br/>[anilist_client.py]"]
end

subgraph group_sync["Bangumi sync"]
  node_bgm_client["Bangumi client<br/>[bgm_client.py]"]
end

subgraph group_setup["Configuration and auth"]
  node_config_loader["Config manager<br/>[config.py]"]
  node_oauth_tool["OAuth authorization<br/>[authorize.py]"]
  node_config_file["Configuration file<br/>[config.py]"]
end

node_mpv_user(("mpv playback"))
node_bangumi{{"Bangumi API"}}
node_anilist{{"AniList API"}}
node_oauth_provider{{"Bangumi OAuth"}}

node_mpv_user -->|"plays video"| node_mpv_script
node_mpv_script -->|"starts sync"| node_sync_entry
node_sync_entry -->|"loads settings"| node_config_loader
node_sync_entry -->|"parses filename"| node_filename_parser
node_sync_entry -->|"resolves title"| node_mapper
node_sync_entry -->|"finds episode"| node_bgm_client
node_sync_entry -->|"marks watched"| node_bgm_client
node_sync_entry -->|"manages mappings"| node_mapper
node_mapper -->|"loads mappings"| node_mapping_files
node_mapper -->|"reads and writes"| node_cache_db
node_mapper -->|"searches subjects"| node_bgm_client
node_mapper -.->|"searches fallback"| node_anilist_client
node_bgm_client -->|"searches and updates"| node_bangumi
node_anilist_client -.->|"searches titles"| node_anilist
node_oauth_tool -->|"exchanges code"| node_oauth_provider
node_oauth_tool -->|"loads and saves tokens"| node_config_loader
node_config_loader -->|"reads and writes"| node_config_file
node_bgm_client -->|"persists refreshed tokens"| node_config_loader

click node_mpv_script "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/main.lua"
click node_sync_entry "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/main.py"
click node_filename_parser "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/parser.py"
click node_config_loader "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/config.py"
click node_mapper "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/mapper.py"
click node_mapping_files "https://github.com/yangpz005/mpv-to-bgm/tree/main/scripts/mpv-to-bgm"
click node_cache_db "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/mapper.py"
click node_bgm_client "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/bgm_client.py"
click node_anilist_client "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/anilist_client.py"
click node_oauth_tool "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/authorize.py"
click node_config_file "https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/config.py"

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_mpv_script,node_sync_entry,node_filename_parser toneBlue
class node_mapper,node_mapping_files,node_cache_db,node_anilist_client toneAmber
class node_bgm_client,node_bangumi,node_anilist toneMint
class node_config_loader,node_oauth_tool,node_config_file toneRose
class node_mpv_user,node_oauth_provider toneIndigo
```

## Components

### Playback intake

- [mpv Lua plugin](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/main.lua): `scripts/mpv-to-bgm/main.lua`
- [Sync and CLI](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/main.py): `scripts/mpv-to-bgm/src/main.py`
- [Filename parser](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/parser.py): `scripts/mpv-to-bgm/src/parser.py`

### Title matching

- [Title mapper](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/mapper.py): `scripts/mpv-to-bgm/src/mapper.py`
- [Mappings and aliases](https://github.com/yangpz005/mpv-to-bgm/tree/main/scripts/mpv-to-bgm): `scripts/mpv-to-bgm`
- [Mapping and sync cache](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/mapper.py): `scripts/mpv-to-bgm/src/mapper.py`
- [AniList client](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/anilist_client.py): `scripts/mpv-to-bgm/src/anilist_client.py`

### Bangumi sync

- [Bangumi client](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/bgm_client.py): `scripts/mpv-to-bgm/src/bgm_client.py`

### Configuration and auth

- [Config manager](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/config.py): `scripts/mpv-to-bgm/src/config.py`
- [OAuth authorization](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/authorize.py): `scripts/mpv-to-bgm/src/authorize.py`
- [Configuration file](https://github.com/yangpz005/mpv-to-bgm/blob/main/scripts/mpv-to-bgm/src/config.py): `scripts/mpv-to-bgm/src/config.py`

### Other components

- **mpv playback**
- **Bangumi API**
- **AniList API**
- **Bangumi OAuth**

## Connections

- mpv playback → mpv Lua plugin: plays video
- mpv Lua plugin → Sync and CLI: starts sync
- Sync and CLI → Config manager: loads settings
- Sync and CLI → Filename parser: parses filename
- Sync and CLI → Title mapper: resolves title
- Sync and CLI → Bangumi client: finds episode
- Sync and CLI → Bangumi client: marks watched
- Sync and CLI → Title mapper: manages mappings
- Title mapper → Mappings and aliases: loads mappings
- Title mapper → Mapping and sync cache: reads and writes
- Title mapper → Bangumi client: searches subjects
- Title mapper → AniList client: searches fallback
- Bangumi client → Bangumi API: searches and updates
- AniList client → AniList API: searches titles
- OAuth authorization → Bangumi OAuth: exchanges code
- OAuth authorization → Config manager: loads and saves tokens
- Config manager → Configuration file: reads and writes
- Bangumi client → Config manager: persists refreshed tokens