# goat095/macground architecture

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

- Interactive diagram: https://gitdiagram.com/goat095/macground
- Repository: https://github.com/goat095/macground

## Overview

Macground is a macOS wallpaper application for video and animated GIFs. The principal workflow takes a media file or folder through CLI selection, then applies it to the desktop, lock screen, or both. Desktop playback includes playlist rotation, native menu controls, and power-aware pausing; the lock-screen path converts media for macOS Aerial slots and updates system wallpaper state. The single 90 KB source file is only partially excerpted, so relationships for documented features are cited to the README rather than treated as inspected implementation details.

Main entry points: [`Macground.py`](https://github.com/goat095/macground/blob/main/Macground.py) (CLI workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Media"]
  node_cli["CLI workflow<br/>[Macground.py]"]
  node_media["Media selection<br/>[Macground.py]"]
  node_playlist["Playlist rotation<br/>[Macground.py]"]
end

subgraph group_desktop["Desktop Playback"]
  node_desktop_player["Desktop player<br/>[Macground.py]"]
  node_menu["Menu bar controls<br/>[Macground.py]"]
  node_power["Power-aware pausing<br/>[Macground.py]"]
  node_looping["Loop and speed<br/>[Macground.py]"]
end

subgraph group_lockscreen["Lock Screen"]
  node_converter["4K media conversion<br/>[Macground.py]"]
  node_aerial["Aerial slot setup<br/>[Macground.py]"]
  node_lockscreen_apply["Lock-screen apply<br/>[Macground.py]"]
  node_restore["Backup and restore<br/>[Macground.py]"]
end

subgraph group_management["App Management"]
  node_app_bundle["Standalone app bundle<br/>[Macground.py]"]
  node_startup["Login startup<br/>[Macground.py]"]
end

node_user(("User"))
node_macos_desktop["macOS desktop"]
node_system_wallpaper[("macOS wallpaper state")]
node_launch_agent["LaunchAgent"]

node_user -->|"selects media"| node_cli
node_cli -->|"selects input"| node_media
node_media -->|"provides files"| node_playlist
node_playlist -->|"rotates wallpapers"| node_desktop_player
node_cli -->|"starts playback"| node_desktop_player
node_desktop_player -->|"displays wallpaper"| node_macos_desktop
node_menu -->|"controls playback"| node_desktop_player
node_power -->|"pauses playback"| node_desktop_player
node_looping -->|"sets playback"| node_desktop_player
node_cli -->|"starts conversion"| node_converter
node_converter -->|"creates media"| node_aerial
node_aerial -->|"configures slots"| node_lockscreen_apply
node_lockscreen_apply -->|"updates state"| node_system_wallpaper
node_restore -->|"restores state"| node_system_wallpaper
node_cli -->|"builds or installs"| node_app_bundle
node_cli -->|"configures startup"| node_startup
node_startup -->|"creates or removes"| node_launch_agent

click node_cli "https://github.com/goat095/macground/blob/main/Macground.py"
click node_media "https://github.com/goat095/macground/blob/main/Macground.py"
click node_playlist "https://github.com/goat095/macground/blob/main/Macground.py"
click node_desktop_player "https://github.com/goat095/macground/blob/main/Macground.py"
click node_menu "https://github.com/goat095/macground/blob/main/Macground.py"
click node_power "https://github.com/goat095/macground/blob/main/Macground.py"
click node_looping "https://github.com/goat095/macground/blob/main/Macground.py"
click node_converter "https://github.com/goat095/macground/blob/main/Macground.py"
click node_aerial "https://github.com/goat095/macground/blob/main/Macground.py"
click node_lockscreen_apply "https://github.com/goat095/macground/blob/main/Macground.py"
click node_restore "https://github.com/goat095/macground/blob/main/Macground.py"
click node_app_bundle "https://github.com/goat095/macground/blob/main/Macground.py"
click node_startup "https://github.com/goat095/macground/blob/main/Macground.py"

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_cli,node_media,node_playlist,node_user toneBlue
class node_desktop_player,node_menu,node_power,node_looping,node_system_wallpaper toneAmber
class node_converter,node_aerial,node_lockscreen_apply,node_restore toneMint
class node_app_bundle,node_startup toneRose
class node_macos_desktop,node_launch_agent toneIndigo
```

## Components

### Entry and Media

- [CLI workflow](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Media selection](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Playlist rotation](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`

### Desktop Playback

- [Desktop player](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Menu bar controls](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Power-aware pausing](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Loop and speed](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`

### Lock Screen

- [4K media conversion](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Aerial slot setup](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Lock-screen apply](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Backup and restore](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`

### App Management

- [Standalone app bundle](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`
- [Login startup](https://github.com/goat095/macground/blob/main/Macground.py): `Macground.py`

### Other components

- **User**
- **macOS desktop**
- **macOS wallpaper state**
- **LaunchAgent**

## Connections

- User → CLI workflow: selects media (evidence: `README.md`)
- CLI workflow → Media selection: selects input (evidence: `README.md`)
- Media selection → Playlist rotation: provides files (evidence: `README.md`)
- Playlist rotation → Desktop player: rotates wallpapers (evidence: `README.md`)
- CLI workflow → Desktop player: starts playback (evidence: `README.md`)
- Desktop player → macOS desktop: displays wallpaper (evidence: `README.md`)
- Menu bar controls → Desktop player: controls playback (evidence: `README.md`)
- Power-aware pausing → Desktop player: pauses playback (evidence: `README.md`)
- Loop and speed → Desktop player: sets playback (evidence: `README.md`)
- CLI workflow → 4K media conversion: starts conversion (evidence: `README.md`)
- 4K media conversion → Aerial slot setup: creates media (evidence: `README.md`)
- Aerial slot setup → Lock-screen apply: configures slots (evidence: `README.md`)
- Lock-screen apply → macOS wallpaper state: updates state (evidence: `README.md`)
- Backup and restore → macOS wallpaper state: restores state (evidence: `README.md`)
- CLI workflow → Standalone app bundle: builds or installs (evidence: `README.md`)
- CLI workflow → Login startup: configures startup (evidence: `README.md`)
- Login startup → LaunchAgent: creates or removes (evidence: `README.md`)