# dayanch96/ytmusicultimate architecture

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

- Interactive diagram: https://gitdiagram.com/dayanch96/ytmusicultimate
- Repository: https://github.com/dayanch96/ytmusicultimate

## Overview

##### Project Type & Purpose
- YTMusicUltimate is an iOS jail­break tweak built with Theos/Logos that injects into the YouTube Music app to extend/modify its behavior (e.g., background play, disable ads, sponsor block).
- It’s not a full-stack app or service, but rather a dynamically loaded library (.dylib) plus a Preference.bundle for Settings.app, packaged as a .deb for Cydia or a repackaged .ipa for sideloading.

##### File‐Tree Analysis
- Top‐Level:
- Makefile (Theos build script)
- Resources/depiction.json (Cydia repository metadata)
- Sideloading.xm (logos file for IPA injection)
- control (package metadata)
- layout/… (install paths for bundle files)
- Source/: The core Logos (.xm/.x) modules, each enabling a tweak feature:
- AVSwitching.xm, BackgroundPlayback.xm, DisableAutoPlay.xm, etc.
- Prefs/ (Objective-C view controllers for the Settings bundle)
- Headers/ (reverse-engineered YouTube Music class interfaces used for hooking)
- Utils/: Third-party libraries embedded in-tweak:
- MBProgressHUD for in-app progress UI
- MobileFFmpeg (headers + .a static libs) for media downloading/processing
- VolumeBar/: Custom volume UI component
- Layout/: Defines where files go in /Library/Application Support/YTMusicUltimate.bundle
- .github/, README.md, LICENSE, etc., are for repo management.

##### README Insights
- Describes distribution (Cydia repo vs. sideload) and build flows:
- Theos “make package” for .deb
- GitHub Actions workflow for .ipa injection

a. Main Components
1. Host Environment: iOS device + YouTube Music app
2. Injection Framework: Cydia Substrate or Substitute
3. YTMusicUltimate.dylib (compiled Logos modules)
– Feature Modules (.xm/.x)
– Embedded Libraries (MobileFFmpeg, MBProgressHUD)
4. Preference.bundle (loaded by Settings.app)
5. Build & Deployment Pipelines:
– Theos make system
– GitHub Actions for IPA sideload
b. Relationships & Interactions
- Theos compiles Source/ and Utils/ into a dynamic library.
- At app launch, Substrate injects YTMusicUltimate.dylib into YouTube Music’s process.
- Logos hooks (Source/*.xm) intercept calls to YouTube Music classes (declared in Headers/) to modify behavior.
- Embedded FFmpeg library handles download/processing flows invoked by hook code.
- Preference.bundle communicates via CFPreferences to toggle tweak flags at runtime.
- For sideloading, GitHub Actions workflow: fetch decrypted .ipa → insert dylib + Preference.bundle → repackage → publish.
c. Architectural Patterns & Principles
- Plugin / Hooking Pattern: logos-based runtime method swizzling / class injection
- Modular Design: each tweak feature in its own .xm file
- Separation of Concerns:
- UI hooks vs. playback hooks vs. network/download logic
- Settings UI isolated in Prefs/
- Embedded Static Linking for heavy libs (FFmpeg) to avoid external dependencies
d. Key Technologies & Frameworks
- Logos (Theos) for hooking
- Substrate/Substitute as injection engine
- MobileFFmpeg (C library) for media processing
- MBProgressHUD for in-app UI
- Theos build system
- GitHub Actions for CI/CD sideload IPA builds

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Pipeline
    subgraph "Build & Deployment Pipeline"
        Makefile["Makefile"]:::build
        Control["control"]:::build
        Depiction["Resources/depiction.json"]:::build
        CI[".github/workflows/main.yml"]:::build
        Sideloading["Sideloading.xm"]:::build
        Makefile -->|"includes metadata"| Control
        Makefile -->|"includes metadata"| Depiction
        Makefile -->|"compile Logos modules"| YTLib["YTMusicUltimate.dylib"]:::runtime
        CI -->|"fetch .ipa & inject"| IPA["Modified .ipa"]:::build
        Sideloading -->|"Logos scripts used"| IPA
        Makefile -->|"make package (.deb)"| Deb[".deb Package"]:::build
        Deb -->|"deploy"| Device
        IPA -->|"deploy"| Device
    end

    %% Deployment Layout
    subgraph "Deployment Layout"
        Layout["/Library/Application Support/YTMusicUltimate.bundle"]:::deployment
    end
    Deb --> Layout
    IPA --> Layout

    %% Runtime on Device
    Device["iOS Device"]:::runtime
    Device -->|"launch"| App["YouTube Music App"]:::runtime
    App -->|"inject via Substrate/Substitute"| Injector["Injection Engine"]:::runtime
    Injector -->|"loads"| YTLib
    YTLib -->|"hooks into"| HostClasses["YouTube Music Classes"]:::runtime

    %% Hook Modules within dylib
    subgraph "Hook Modules (Logos .xm)" 
        UIHooks["UI Modification Hooks"]:::runtime
        PlaybackHooks["Playback Control Hooks"]:::runtime
        DownloadHooks["Downloader Hooks"]:::runtime
        OtherHooks["Other Feature Hooks"]:::runtime
        YTLib --> UIHooks
        YTLib --> PlaybackHooks
        YTLib --> DownloadHooks
        YTLib --> OtherHooks

        AVSwitching["AVSwitching.xm"]:::runtime
        BackgroundPlayback["BackgroundPlayback.xm"]:::runtime
        DisableAutoPlay["DisableAutoPlay.xm"]:::runtime
        SponsorBlock["SponsorBlock.xm"]:::runtime
        PremiumStatus["PremiumStatus.xm"]:::runtime

        UIHooks --> AVSwitching
        PlaybackHooks --> BackgroundPlayback
        PlaybackHooks --> DisableAutoPlay
        UIHooks --> SponsorBlock
        OtherHooks --> PremiumStatus
    end

    %% Embedded Libraries
    subgraph "Embedded Libraries"
        MBHUD["MBProgressHUD"]:::thirdparty
        FFmpeg["MobileFFmpeg"]:::thirdparty
        YTLib --> MBHUD
        YTLib --> FFmpeg
    end

    %% Custom Volume UI Component
    VolumeComp["Custom VolumeBar Component"]:::runtime
    YTLib --> VolumeComp

    %% Preference Bundle and Settings
    subgraph "Preference Bundle (Settings.app)"
        PrefBundle["YTMusicUltimate Preferences"]:::runtime
        NavBarUI["NavBarSettingsController.{h,m}"]:::runtime
        PlayerUI["PlayerSettingsController.{h,m}"]:::runtime
        PremiumUI["PremiumSettingsController.{h,m}"]:::runtime
        TabBarUI["TabBarSettingsController.{h,m}"]:::runtime
        ThemeUI["ThemeSettingsController.{h,m}"]:::runtime
        DownloadsUI["YTMDownloads.{h,m}"]:::runtime
        MainUI["YTMUltimateSettingsController.{h,m}"]:::runtime
        PrefBundle --> NavBarUI
        PrefBundle --> PlayerUI
        PrefBundle --> PremiumUI
        PrefBundle --> TabBarUI
        PrefBundle --> ThemeUI
        PrefBundle --> DownloadsUI
        PrefBundle --> MainUI
    end
    SettingsApp["Settings.app"]:::runtime
    SettingsApp --> PrefBundle
    PrefBundle -->|"CFPreferences API"| YTLib

    %% Legend and classDefs
    classDef build fill:#e2fdf4,stroke:#20c997;
    classDef runtime fill:#e9f5ff,stroke:#4098d7;
    classDef thirdparty fill:#fff4e6,stroke:#f76707;
    classDef deployment fill:#f1f3f5,stroke:#adb5bd;

    %% Click Events
    click Makefile "https://github.com/dayanch96/ytmusicultimate/tree/main/Makefile"
    click CI "https://github.com/dayanch96/ytmusicultimate/blob/main/.github/workflows/main.yml"
    click Control "https://github.com/dayanch96/ytmusicultimate/tree/main/control"
    click Depiction "https://github.com/dayanch96/ytmusicultimate/blob/main/Resources/depiction.json"
    click Sideloading "https://github.com/dayanch96/ytmusicultimate/blob/main/Sideloading.xm"
    click AVSwitching "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/AVSwitching.xm"
    click BackgroundPlayback "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/BackgroundPlayback.xm"
    click DisableAutoPlay "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/DisableAutoPlay.xm"
    click SponsorBlock "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/SponsorBlock.xm"
    click PremiumStatus "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/PremiumStatus.xm"
    click MBHUD "https://github.com/dayanch96/ytmusicultimate/tree/main/Source/Utils/MBProgressHUD/"
    click FFmpeg "https://github.com/dayanch96/ytmusicultimate/tree/main/Source/Utils/MobileFFmpeg/"
    click VolumeComp "https://github.com/dayanch96/ytmusicultimate/tree/main/Source/VolumeBar/"
    click NavBarUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/NavBarSettingsController.h"
    click NavBarUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/NavBarSettingsController.m"
    click PlayerUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/PlayerSettingsController.h"
    click PlayerUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/PlayerSettingsController.m"
    click PremiumUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/PremiumSettingsController.h"
    click PremiumUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/PremiumSettingsController.m"
    click TabBarUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/TabBarSettingsController.h"
    click TabBarUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/TabBarSettingsController.m"
    click ThemeUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/ThemeSettingsController.h"
    click ThemeUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/ThemeSettingsController.m"
    click DownloadsUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/YTMDownloads.h"
    click DownloadsUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/YTMDownloads.m"
    click MainUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/YTMUltimateSettingsController.h"
    click MainUI "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Prefs/YTMUltimateSettingsController.m"
    click Layout "https://github.com/dayanch96/ytmusicultimate/tree/main/layout/Library/Application Support/YTMusicUltimate.bundle/"
    click YTLib "https://github.com/dayanch96/ytmusicultimate/blob/main/YTMusicUltimate.dylib"
    click HostClasses "https://github.com/dayanch96/ytmusicultimate/tree/main/Source/Headers/"
    click FFMpegDownloader "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/FFMpegDownloader.h"
    click FFMpegDownloader "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/FFMpegDownloader.m"
    click Downloading "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Downloading.x"
    click Downloading "https://github.com/dayanch96/ytmusicultimate/blob/main/Source/Downloading.h"
```
