# reteps/real-time-lyrics architecture

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

- Interactive diagram: https://gitdiagram.com/reteps/real-time-lyrics
- Repository: https://github.com/reteps/real-time-lyrics

## Overview

1. **Repository shape**
   - This is a small Python application, not a multi-service system.
   - The architecture is centered around two runnable CLI entry points:
     - `acrcloud_cmdline.py`
     - `lyrics_spotify_camera.py`
   - `fads.py` appears to hold shared helper logic used by one or both flows.

2. **Primary runtime**
   - Everything runs locally under Python 3.
   - Dependencies are installed via `requirements.txt`.
   - Configuration is environment-driven, with credentials for external services supplied through env vars such as `ACR_ACCESS_KEY`, `ACR_ACCESS_SECRET`, `SPOTIFY_ID`, and `SPOTIFY_SECRET`.

3. **Workflow A: microphone → recognition → lyric lookup**
   - `acrcloud_cmdline.py` implements the main “real time lyric detection” path.
   - The local machine records audio from the microphone, writes the captured sample to `out.wav`, then sends the audio to ACRCloud for song identification.
   - After a track is identified, the program looks up lyric timing data from LRC lyric sources to map recognized song sections to synchronized lyrics.

4. **Workflow B: Spotify → camera/overlay**
   - `lyrics_spotify_camera.py` is a separate flow focused on whatever song is currently playing in Spotify.
   - It uses Spotify API credentials to identify the current track.
   - The readme indicates it then creates a camera feed via OBS-Camera with lyrics, so the output boundary is a video/camera integration rather than just terminal output.

5. **External service boundaries**
   - **ACRCloud** is the audio recognition boundary for the microphone-based path.
   - **Spotify API** is the track-detection boundary for the camera/overlay path.
   - **LRC lyric sites** are the lyric-source boundary, used after song identification to fetch timed lyrics.
   - These are the main remote dependencies that determine the app’s behavior.

6. **Local data flow and artifacts**
   - The app writes transient files into the working directory:
     - `out.wav` for the captured audio sample
     - `logs/res_dump.json` for the recognition response dump
   - These files are important operational artifacts, not core domain data stores.
   - The presence of `logs/` suggests the system is mostly stateless between runs aside from debug/trace output.

7. **Likely internal layering**
   - The code is probably organized as:
     - CLI orchestration scripts at the top
     - helper/utilities in `fads.py`
     - external API calls for recognition and metadata lookup
     - lyric/timing parsing and display logic
   - There is no sign of a database, web server, queue, or background worker architecture.

8. **Core domain behavior**
   - The domain problem is synchronizing lyrics to a currently playing song.
   - The hard part is not just retrieving lyrics, but aligning them to the correct track segment after recognition.
   - The readme’s bug notes show that recognition confidence and lyric timing alignment are central concerns.

9. **Operational constraints and failure modes**
   - Recognition quality affects the whole pipeline: if ACRCloud matches the wrong snippet or a chorus from the wrong section, lyric timing can drift.
   - The system also depends on the quality of lyric text returned by external LRC sources; heavily censored lyrics can reduce recoverability.
   - This means the architecture is sensitive to upstream metadata quality rather than internal persistence.

10. **What to draw in an architecture diagram**
   - Draw a local Python CLI application split into two entry points.
   - Show a microphone input path feeding ACRCloud, then lyric lookup, then local output.
   - Show a Spotify-based path feeding lyric display through OBS-Camera.
   - Put ACRCloud, Spotify, and LRC lyric sites outside the app boundary.
   - Show `out.wav` and `logs/res_dump.json` as local scratch/debug artifacts.

11. **Repository-level takeaway**
   - This repo is a thin client/orchestrator around third-party audio, music metadata, and lyric services.
   - It does not appear to own a durable backend; its value is in coordinating recognition, lookup, and presentation of synchronized lyrics in real time.

Main entry points: [`acrcloud_cmdline.py`](https://github.com/reteps/real-time-lyrics/blob/master/acrcloud_cmdline.py) (ACRCloud CLI), [`lyrics_spotify_camera.py`](https://github.com/reteps/real-time-lyrics/blob/master/lyrics_spotify_camera.py) (Spotify camera), [`fads.py`](https://github.com/reteps/real-time-lyrics/blob/master/fads.py) (Shared helpers), [`requirements.txt`](https://github.com/reteps/real-time-lyrics/blob/master/requirements.txt) (Dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Local app"]
  node_acrcloud_cmdline["ACRCloud CLI<br/>entrypoint"]
  node_lyrics_spotify_camera["Spotify camera<br/>entrypoint"]
  node_fads["Shared helpers<br/>helper module<br/>[fads.py]"]
  node_mic_input(("Microphone<br/>audio input"))
  node_wav_artifact["out.wav<br/>scratch audio<br/>[out.wav]"]
  node_res_dump["res_dump.json<br/>debug artifact<br/>[res_dump.json]"]
  node_lyric_sync["Lyric sync<br/>timing/parse"]
  node_obs_camera["OBS camera<br/>video output"]
  node_env_vars["Env config<br/>credentials/config"]
  node_requirements["Dependencies<br/>python deps<br/>[requirements.txt]"]
  node_readme["README<br/>usage docs<br/>[readme.md]"]
end

subgraph group_ext["External services"]
  node_acrcloud[("ACRCloud<br/>audio recognition API")]
  node_spotify_api[("Spotify API<br/>track detection API")]
  node_lrc_sites[("LRC sources<br/>lyric source")]
end

node_acrcloud_cmdline -->|"records"| node_mic_input
node_mic_input -->|"writes"| node_wav_artifact
node_acrcloud_cmdline -->|"recognizes"| node_acrcloud
node_acrcloud_cmdline -->|"logs"| node_res_dump
node_acrcloud_cmdline -->|"fetches lyrics"| node_lrc_sites
node_lrc_sites -->|"provides timing"| node_lyric_sync
node_acrcloud_cmdline -->|"aligns"| node_lyric_sync
node_lyrics_spotify_camera -->|"reads track"| node_spotify_api
node_lyrics_spotify_camera -->|"syncs lyrics"| node_lyric_sync
node_lyrics_spotify_camera -->|"outputs"| node_obs_camera
node_fads -.->|"supports"| node_acrcloud_cmdline
node_fads -.->|"supports"| node_lyrics_spotify_camera
node_env_vars -->|"configures"| node_acrcloud
node_env_vars -->|"configures"| node_spotify_api
node_requirements -.->|"installs"| node_acrcloud_cmdline
node_requirements -.->|"installs"| node_lyrics_spotify_camera
node_readme -.->|"documents"| node_acrcloud_cmdline
node_readme -.->|"documents"| node_lyrics_spotify_camera

click node_acrcloud_cmdline "https://github.com/reteps/real-time-lyrics/blob/master/acrcloud_cmdline.py"
click node_lyrics_spotify_camera "https://github.com/reteps/real-time-lyrics/blob/master/lyrics_spotify_camera.py"
click node_fads "https://github.com/reteps/real-time-lyrics/blob/master/fads.py"
click node_wav_artifact "https://github.com/reteps/real-time-lyrics/blob/master/out.wav"
click node_res_dump "https://github.com/reteps/real-time-lyrics/blob/master/logs/res_dump.json"
click node_requirements "https://github.com/reteps/real-time-lyrics/blob/master/requirements.txt"
click node_readme "https://github.com/reteps/real-time-lyrics/blob/master/readme.md"

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_acrcloud_cmdline,node_lyrics_spotify_camera,node_fads,node_mic_input,node_wav_artifact,node_res_dump,node_lyric_sync,node_obs_camera,node_env_vars,node_requirements,node_readme toneBlue
class node_acrcloud,node_spotify_api,node_lrc_sites toneAmber
```

## Components

### Local app

Python CLI application and runtime artifacts

- [ACRCloud CLI](https://github.com/reteps/real-time-lyrics/blob/master/acrcloud_cmdline.py): entrypoint · Main microphone-to-lyrics command line flow · `acrcloud_cmdline.py`
- [Spotify camera](https://github.com/reteps/real-time-lyrics/blob/master/lyrics_spotify_camera.py): entrypoint · Spotify-driven lyrics overlay flow · `lyrics_spotify_camera.py`
- [Shared helpers](https://github.com/reteps/real-time-lyrics/blob/master/fads.py): helper module · Common support logic used by the CLI flows · `fads.py`
- **Microphone**: audio input · Local live audio capture source
- [out.wav](https://github.com/reteps/real-time-lyrics/blob/master/out.wav): scratch audio · Transient captured audio sample · `out.wav`
- [res_dump.json](https://github.com/reteps/real-time-lyrics/blob/master/logs/res_dump.json): debug artifact · Recognition response dump under logs/ · `logs/res_dump.json`
- **Lyric sync**: timing/parse · Maps identified songs to timed lyric sections
- **OBS camera**: video output · Camera/feed integration used for lyric display
- **Env config**: credentials/config · ACR and Spotify credentials provided via environment variables
- [Dependencies](https://github.com/reteps/real-time-lyrics/blob/master/requirements.txt): python deps · Runtime dependencies installed from requirements.txt · `requirements.txt`
- [README](https://github.com/reteps/real-time-lyrics/blob/master/readme.md): usage docs · Project notes and workflow description · `readme.md`

### External services

Remote APIs and lyric sources

- **ACRCloud**: audio recognition API · Remote song identification service
- **Spotify API**: track detection API · Remote track and playback metadata service
- **LRC sources**: lyric source · Timed lyric sites used after recognition

## Connections

- ACRCloud CLI → Microphone: records · Captures live audio from the microphone
- Microphone → out.wav: writes · Stores the captured sample as a WAV file
- ACRCloud CLI → ACRCloud: recognizes · Sends captured audio for song identification
- ACRCloud CLI → res_dump.json: logs · Writes recognition response for inspection
- ACRCloud CLI → LRC sources: fetches lyrics · Uses identified track info to retrieve timed lyrics
- LRC sources → Lyric sync: provides timing · Supplies lyric text and timestamps
- ACRCloud CLI → Lyric sync: aligns · Maps recognition results to synchronized lyric sections
- Spotify camera → Spotify API: reads track · Uses Spotify credentials to detect the current song
- Spotify camera → Lyric sync: syncs lyrics · Aligns current track with lyric timing for display
- Spotify camera → OBS camera: outputs · Feeds lyrics into the camera/overlay integration
- Shared helpers → ACRCloud CLI: supports · Shared helper logic used by the microphone flow
- Shared helpers → Spotify camera: supports · Shared helper logic used by the Spotify flow
- Env config → ACRCloud: configures · Provides ACRCloud access credentials
- Env config → Spotify API: configures · Provides Spotify API credentials
- Dependencies → ACRCloud CLI: installs · Declares runtime dependencies for the CLI app
- Dependencies → Spotify camera: installs · Declares runtime dependencies for the CLI app
- README → ACRCloud CLI: documents · Describes the real-time lyric detection flow
- README → Spotify camera: documents · Describes the Spotify-to-camera flow