reteps/real-time-lyrics

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.