# zhaarey/apple-music-downloader architecture

> Architecture diagram of the GitHub repository zhaarey/apple-music-downloader, 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/zhaarey/apple-music-downloader
- Repository: https://github.com/zhaarey/apple-music-downloader

## Overview

##### Main Components
- Entry Point: The main.go file serves as the main entry point of the application. This is where command-line arguments are parsed and the overall workflow is coordinated.
- Configuration: The config.yaml file (and perhaps the config handling in main.go) is used to specify user-specific settings, including tokens required for fetching media and lyric information.
- Download Manager: The workflow in main.go leads to modules responsible for fetching albums, single songs, playlists, and other types of Apple Music content. This “download manager” logic will branch into different operational paths based on user parameters (e.g., --song, --select, --atmos, --aac).
- Decryption Modules:
- runv2 (in utils/runv2) contains an older decryption module.
- runv3 (in utils/runv3) is a newer decryption path. It includes sub-folders:
◦ cdm: Contains files (cdm.go, pssh.go, wv_proto2.pb.go, consts.go) that likely implement the decryption protocol/logic.
◦ key: Contains key-related functions for decryption.
- Lyrics Module: Located in utils/lyrics, this module appears dedicated to handling embedded lyrics extraction and processing.
- Utility Structures: The utils/structs package is likely used to define common data structures shared through the system.
- Agent Scripts: The agent.js and agent-arm64.js files serve specialized roles (with a shout-out to “chocomint” for agent-arm64.js) possibly for handling operations in different runtime environments or platforms.

##### Relationships and Interactions
- The primary data flow starts from main.go reading configurations (from config.yaml) and command-line inputs.
- Based on user input, main.go directs the flow to the appropriate managers:
- For song/album/playlist downloads, main.go routes the requests to the download logic (likely interacting with code in runv2 or runv3 as appropriate for decryption).
- Once downloaded, if there are lyrics or artwork tasks, the “lyrics” module and possibly parts of “utils/structs” are invoked.
- Decryption modules (runv2 vs. runv3) are separated—each encapsulating their specific decryption algorithms and possibly interfacing with external decryption tools (like mp4decrypt, as mentioned in the README) and a wrapper component.
- External dependencies (like MP4Box and mp4decrypt) are not part of the codebase but are crucial for the tool, so indicate them as external systems that the tool interacts with via command-line calls or API integrations.
- The JS agent files should be illustrated as auxiliary components that might be invoked by the Go code (or used externally) to support some of the decryption or media processing tasks on different architectures.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into directories such as utils/lyrics, utils/runv2, utils/runv3, and utils/structs emphasizes separation of concerns.
- Dependency on External Tools: Clearly show interactions with external utilities like MP4Box and mp4decrypt.
- Command-Line Driven workflow: Showcase that the application is primarily driven by CLI arguments, which then determine the flow to various modules.

##### Technologies, Frameworks, and Libraries
- Go as the primary language with its go.mod and go.sum files showing dependency management.
- Use of YAML for configuration.
- Integration with external CLI tools (MP4Box, mp4decrypt) as noted in the README.
- JavaScript components may hint at cross-platform considerations (for example, supporting ARM64 or other environments).

##### Elements
- Also explicitly mark versioned paths (runv2 vs. runv3) so one can quickly see which decryption strategies are available.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Configuration
    subgraph "CLI Configuration"
        A["CLI/Main Entry (main.go)"]:::primary
        B["Configuration (config.yaml)"]:::primary
    end
    A -->|"reads_config"| B

    %% Download Workflow
    subgraph "Download Workflow"
        C["Download Manager (main.go)"]:::primary
    end
    A -->|"initiates_download"| C

    %% Decryption Modules
    subgraph "Decryption Modules"
        D["Decryption Module v2"]:::primary
        D1["Runv2 Module"]:::primary
        D -->|"v2_logic"| D1

        E["Decryption Module v3"]:::primary
        E1["Runv3 Module"]:::primary
        subgraph "Runv3 Submodules"
            F["CDM Module"]:::primary
            G["Key Handling"]:::primary
        end
        E -->|"v3_logic"| E1
        E1 -->|"uses"| F
        E1 -->|"uses"| G

        %% Download Manager routes to chosen decryption module
        C -->|"uses_v2_or_v3"| D
        C -->|"uses_v2_or_v3"| E
    end

    %% Ancillary Modules
    subgraph "Ancillary Modules"
        H["Lyrics Module"]:::primary
        I["Utility Structures"]:::primary
    end
    C -->|"processes"| H
    C -->|"utilizes"| I

    %% External Tools
    subgraph "External Tools"
        J["MP4Box"]:::external
        K["mp4decrypt"]:::external
    end
    C -->|"invokes"| J
    C -->|"invokes"| K

    %% Agent Scripts
    subgraph "Agent Scripts"
        L["agent.js"]:::primary
        M["agent-arm64.js"]:::primary
    end
    C -->|"triggers"| L
    C -->|"triggers"| M

    %% Click Events
    click A "https://github.com/zhaarey/apple-music-downloader/blob/main/main.go"
    click B "https://github.com/zhaarey/apple-music-downloader/blob/main/config.yaml"
    click C "https://github.com/zhaarey/apple-music-downloader/blob/main/main.go"
    click D1 "https://github.com/zhaarey/apple-music-downloader/blob/main/utils/runv2/runv2.go"
    click E "https://github.com/zhaarey/apple-music-downloader/blob/main/utils/runv3/runv3.go"
    click F "https://github.com/zhaarey/apple-music-downloader/tree/main/utils/runv3/cdm"
    click G "https://github.com/zhaarey/apple-music-downloader/blob/main/utils/runv3/key/key.go"
    click H "https://github.com/zhaarey/apple-music-downloader/blob/main/utils/lyrics/lyrics.go"
    click I "https://github.com/zhaarey/apple-music-downloader/blob/main/utils/structs/structs.go"
    click L "https://github.com/zhaarey/apple-music-downloader/blob/main/agent.js"
    click M "https://github.com/zhaarey/apple-music-downloader/blob/main/agent-arm64.js"

    %% Styles
    classDef primary fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef external fill:#F7D6AE,stroke:#333,stroke-width:2px;
```
