# chrisdonahue/sheetsage architecture

> Architecture diagram of the GitHub repository chrisdonahue/sheetsage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chrisdonahue/sheetsage
- Repository: https://github.com/chrisdonahue/sheetsage

## Overview

##### Main Components
- Command-line Interface & Script Launcher: The main shell scripts (sheetsage.sh, prepare.sh, sheetsage.sh) act as the entry points for setup and transcription – they handle user input (e.g., a YouTube URL or local file path) and kick-off processing.
- Core Transcription Engine (“sheetsage” Package): This component comprises the bulk of the processing code. Within the sheetsage directory, there are submodules handling multiple aspects:
- Alignment (align.py, align_test.py)
- Beat and tempo detection (beat_track.py, beat_track_test.py)
- Data management (data.py and data_test.py)
- Evaluation (eval.py, eval_test.py)
- Inference (infer.py, infer_test.py)
- Various modules for representations (both handcrafted and using Jukebox) and theoretical music processing (under theory/)
- Utility functions in utils.py
- Assets/Models and Data: Located under sheetsage/assets, this includes configuration files (like sheetsage.json), musical JSON data for HookTheory, and other auxiliary data required for both training and inference.
- Serving Backend: Under sheetsage/serve/backend, there is a backend main application intended to support server-side transcription or a hosted API.
- Docker Infrastructure: The docker and cloudrun directories provide Dockerfiles and scripts (e.g., run.sh, build.sh, shell.sh) enabling containerized development, testing, and deployment.
- Notebooks: The project includes notebooks (e.g., Inference.ipynb and Dataset.ipynb) that demonstrate usage for both dataset exploration and transcription with interactive environments.
- External Dependencies & Licensing: The README refers to other components like madmom, OpenAI Jukebox, and Melisma, which are integral to transcription quality improvements and beat/downbeat detection. Licensing considerations also mark this as a tool with multiple integration points.

##### Relationships & Data Flow Between Components
- The user starts by running a shell script (e.g., sheetsage.sh) which determines the source of input (YouTube URL or local file).
- This launcher delegates to the core transcription engine where the audio processing happens:
- First, preprocessing (beat detection and possibly downbeat correction) is conducted.
- Then, the transcription modules (inference module, alignment, and theory-based modules) convert the audio features into a lead sheet (chords & melody) and produce intermediary representations (like MIDI files and LilyPond files for rendering).
- The output is then saved to an “output” directory.
- For development and testing, Docker scripts allow this entire pipeline to run inside containers; similarly, Jupyter notebooks help in interactive debugging and exploration.
- For service or API use, a dedicated backend (in sheetsage/serve/backend) could be used – for example, to accept requests and return transcription results.

##### Architectural Patterns & Design Principles
- Layered Architecture: The design naturally separates user interfacing (shell scripts, command-line), core audio and music-driven processing (transcription engine), and external serving components.
- Modular Design: Each logical part (alignment, beat tracking, representation, data handling) is broken up into its own module and tested individually (as seen with “_test.py” files).
- Containerization: Docker and Cloud Run directories show design for consistent build environments and service deployment.
- Extensibility: Support for integration with both “handcrafted” and “jukebox” representations implies an architecture designed to plug in additional models or processing techniques based on the configuration.

##### Final Recommendations for the Principal Software Engineer
- Use annotations to note which directories or files map onto which component (e.g., “sheetsage/theory” for music theory processing, “docker/” for container scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level: User Input
    UI["User Input (URL/File)"]:::ui

    %% CLI & Script Launcher Subgraph
    subgraph "CLI & Script Launcher"
        CLI1["sheetsage.sh"]:::cli
        CLI2["prepare.sh"]:::cli
    end

    %% Core Transcription Engine Subgraph
    subgraph "Core Transcription Engine"
        A["Audio Processing: Beat Detection"]:::engine
        B["Alignment Module"]:::engine
        C["Inference Module"]:::engine
        D["Data Management"]:::engine
        E["Evaluation Module"]:::engine
        F["Representation Modules"]:::engine
        G["Theory Processing"]:::engine
        H["Utility Functions"]:::engine
        I["Output Generation (Lead Sheet, MIDI, LilyPond)"]:::engine
    end

    %% Assets / Models & Data
    Assets["Assets/Models & Data"]:::assets

    %% Serving Backend
    Backend["Serving Backend"]:::backend

    %% Deployment & Development Subgraph
    subgraph "Deployment & Development"
        D1["Docker Infrastructure"]:::deployment
        D2["Cloud Run Deployment"]:::deployment
        D3["Jupyter Notebooks"]:::deployment
    end

    %% Data Flow Connections
    UI --> CLI1
    UI --> CLI2
    CLI1 --> A
    CLI2 --> A
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    Assets --- E
    I --> Backend
    D1 --- CLI1
    D1 --- CLI2
    D2 --- Backend
    D3 --- A

    %% Styles
    classDef ui fill:#d0e9ff,stroke:#036,stroke-width:2px;
    classDef cli fill:#ffe0cc,stroke:#c65,stroke-width:2px;
    classDef engine fill:#e0ffcc,stroke:#393,stroke-width:2px;
    classDef assets fill:#fff2cc,stroke:#996,stroke-width:2px;
    classDef backend fill:#ffd6cc,stroke:#c63,stroke-width:2px;
    classDef deployment fill:#e6ccff,stroke:#836,stroke-width:2px;

    %% Click Events for CLI & Script Launcher
    click CLI1 "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage.sh"
    click CLI2 "https://github.com/chrisdonahue/sheetsage/blob/main/prepare.sh"

    %% Click Events for Core Transcription Engine Components
    click A "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/beat_track.py"
    click B "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/align.py"
    click C "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/infer.py"
    click D "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/data.py"
    click E "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/eval.py"
    click F "https://github.com/chrisdonahue/sheetsage/tree/main/sheetsage/representations/"
    click G "https://github.com/chrisdonahue/sheetsage/tree/main/sheetsage/theory/"
    click H "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/utils.py"

    %% Click Event for Assets/Models
    click Assets "https://github.com/chrisdonahue/sheetsage/tree/main/sheetsage/assets/"

    %% Click Event for Serving Backend
    click Backend "https://github.com/chrisdonahue/sheetsage/blob/main/sheetsage/serve/backend/main.py"

    %% Click Events for Deployment & Development Components
    click D1 "https://github.com/chrisdonahue/sheetsage/tree/main/docker/"
    click D2 "https://github.com/chrisdonahue/sheetsage/tree/main/cloudrun/"
    click D3 "https://github.com/chrisdonahue/sheetsage/tree/main/notebooks/"
```
