Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md
• Dockerfile
• config.yaml
• go.mod
• utils/runv3/cdm/wv_proto2.pb.go
• utils/runv3/key/key.go
• utils/runv3/cdm/cdm.go
• utils/runv3/cdm/pssh.go
• utils/runv3/cdm/consts.go
• main.go

Voraussetzungen und Installation

Systemanforderungen und Abhängigkeiten

Der Apple Music Downloader benötigt zwingend die Installation von MP4Box vor der ersten Nutzung. Dieses Werkzeug muss korrekt in den Systemumgebungsvariablen hinterlegt sein (README.md:1-16). Für den Download von MV-Dateien (Musikvideos) ist zusätzlich mp4decrypt erforderlich.

Das Projekt basiert auf Go 1.23.1 und nutzt mehrere Kernabhängigkeiten, darunter github.com/grafov/m3u8, github.com/spf13/pflag und google.golang.org/protobuf (go.mod:1-12). Diese werden automatisch beim Build-Prozess verwaltet.

Docker-Installation (Empfohlen)

Die Docker-Variante bietet die einfachste Installationsmethode. Das Dockerfile verwendet ein mehrstufiges Build-Verfahren mit golang:1.25.5-alpine als Builder und gpac/ubuntu als Laufzeitumgebung (Dockerfile:1-22).

bash
1# Hilfe anzeigen
2docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --help
3
4# Album herunterladen
5docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader https://music.apple.com/ru/album/children-of-forever/1443732441

Die Docker-Konfiguration installiert automatisch FFmpeg und richtet die Ordnerstruktur für ALAC-, Atmos- und AAC-Downloads ein (Dockerfile:13-21).

Native Go-Installation

Für die native Ausführung ist ein funktionierendes Go-Development-Kit erforderlich. Der Befehl go run main.go startet das Tool direkt aus dem Quellcode (README.md:68-77).

Grundlegende Nutzung

Download-Szenarien

Das Tool unterstützt verschiedene Download-Modi für Alben, einzelne Songs und Playlists. Die Docker-Variante nutzt --network host für die Netzwerkkommunikation und mountet das Download-Verzeichnis (README.md:30-59).

bash
1# Einzelnen Song herunterladen
2docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --song https://music.apple.com/ru/album/bass-folk-song/1443732441?i=1443732453
3
4# Interaktive Auswahl
5docker run -it --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --select https://music.apple.com/ru/album/children-of-forever/1443732441
6
7# Playlist herunterladen
8docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader https://music.apple.com/us/playlist/taylor-swift-essentials/pl.3950454ced8c45a3b0cc693c2a7db97b

Audioformat-Optionen

Das Projekt unterstützt mehrere Audioformate mit entsprechenden Kommandozeilenflags:

• ALAC (Standard): Verlustfreie Qualität
• Dolby Atmos: --atmos Flag für räumliches Audio (README.md:51-52)
• AAC: --aac Flag für komprimiertes Audio (README.md:54-55)

bash
1# Dolby Atmos Download
2docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --atmos https://music.apple.com/us/album/1989-taylors-version-deluxe/1713845538
3
4# AAC Download
5docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --aac https://music.apple.com/us/album/1989-taylors-version-deluxe/1713845538

Native Ausführungsbefehle

Die native Go-Ausführung bietet identische Funktionalität ohne Docker-Overhead (README.md:68-77):

bash
1# Album herunterladen
2go run main.go https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511
3
4# Einzelnen Song
5go run main.go --song https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512
6
7# Debug-Modus für Qualitätsprüfung
8go run main.go --debug https://music.apple.com/ru/album/miles-smiles/209407331

Konfiguration

Authentifizierung einrichten

Für den Zugriff auf geschützte Inhalte (AAC-LC, MV, Lyrics) ist ein gültiger media-user-token erforderlich. Dieser wird über die Browser-Entwicklertools von Apple Music extrahiert (README.md:80-86).

Schritte zur Token-Ermittlung:

1. Apple Music im Browser öffnen und anmelden
2. Entwicklertools öffnen → Application → Storage → Cookies → https://music.apple.com
3. Cookie media-user-token kopieren
4. Wert in config.yaml eintragen

yaml
1media-user-token: "your-media-user-token"
2authorization-token: "your-authorization-token"  # Wird automatisch aktualisiert

Die Konfigurationsdatei definiert Standardwerte für Authentifizierung und Formateinstellungen (config.yaml:1-24).

Download-Pfade und Formateinstellungen

Die config.yaml steuert die Ordnerstruktur und Dateinamen-Konventionen:

yaml
1alac-save-folder: AM-DL downloads
2atmos-save-folder: AM-DL-Atmos downloads
3aac-save-folder: AM-DL-AAC downloads
4mv-save-folder: AM-DL-MV downloads
5
6album-folder-format: "{AlbumName}"
7song-file-format: "{SongNumer}. {SongName}"
8artist-folder-format: "{UrlArtistName}"

In der Docker-Variante werden diese Pfade automatisch auf /downloads/ Unterverzeichnisse umgeleitet (Dockerfile:19-21).

Erweiterte Konvertierungsoptionen

Das Projekt unterstützt die Nachbearbeitung mit FFmpeg. Die Konfiguration bietet umfangreiche Einstellungen für Formatkonvertierungen (config.yaml:54-66):

yaml
1convert-after-download: false      # Nach-Download-Konvertierung aktivieren
2convert-format: "flac"             # Zielformat: flac | mp3 | opus | wav | copy
3convert-keep-original: false       # Originaldatei behalten
4ffmpeg-path: "ffmpeg"              # FFmpeg-Pfad überschreiben
5convert-with-metadata: true        # Metadaten beibehalten
6convert-warn-lossy-to-lossless: true  # Warnung bei verlustbehaftet zu verlustfrei

Docker-Konfigurationsanpassung

Die Standardkonfiguration kann durch Mounten einer eigenen config.yaml überschrieben werden:

bash
1docker run --network host -v ./downloads:/downloads -v ./config.yaml:/app/config.yaml ghcr.io/zhaarey/apple-music-downloader [args]

Wichtig: Die Datei ./config.yaml muss vor dem Ausführen existieren, da Docker sonst ein Verzeichnis statt einer Datei erstellt (README.md:61-66).

Lyrics und erweiterte Funktionen

Songtext-Download

Das Projekt unterstützt das Herunterladen von eingebetteten Lyrics und LRC-Dateien. Hierfür ist zwingend ein media-user-token erforderlich (README.md:7-12).

yaml
1lrc-type: "lyrics"        # lyrics oder syllable-lyrics
2lrc-format: "lrc"         # lrc oder ttml
3embed-lrc: true           # Lyrics in Datei einbetten
4save-lrc-file: false      # Separate LRC-Datei speichern

Übersetzungen und Aussprache-Lyrics (Beta)

Für übersetzte und phonetische Lyrics ist die Beta-Version von Apple Music erforderlich. Die Funktion nutzt die syllable-lyrics-API (README.md:88-102).

Einrichtungsschritte:

1. https://beta.music.apple.com öffnen und anmelden
2. Entwicklertools → Network-Tab öffnen
3. Song mit verfügbarer Übersetzung abspielen (empfohlen: K-Pop)
4. Netzwerk-Traffic nach syllable-lyrics filtern
5. Sprachparameter aus der URL kopieren: .../syllable-lyrics?l=<sprachwert>&extend=ttmlLocalizations
6. Wert in config.yaml unter language eintragen

Interaktive Suche und Künstler-Downloads

Das Tool bietet eine interaktive Suche mit Pfeiltasten-Navigation sowie automatische Album-Erkennung für Künstler (README.md:7-12):

bash
1# Interaktive Suche
2go run main.go --search song "taylor swift"
3
4# Alle Alben eines Künstlers
5go run main.go https://music.apple.com/us/artist/taylor-swift/159260351 --all-album

Schnellstart-Workflow

正在加载图表渲染器...

Verifikation und Testlauf

Erfolgreiche Installation prüfen

Nach der Installation kann die Funktionalität mit einem Test-Download verifiziert werden:

bash
1# Debug-Modus für detaillierte Ausgabe
2docker run --network host -v ./downloads:/downloads ghcr.io/zhaarey/apple-music-downloader --debug https://music.apple.com/ru/album/miles-smiles/209407331

Bei erfolgreicher Ausführung erscheinen heruntergeladene Dateien im gemounteten ./downloads-Verzeichnis. Die Debug-Ausgabe zeigt die verfügbaren Qualitätsstufen (README.md:57-58).

Wrapper-Dienst verifizieren

Der Entschlüsselungs-Wrapper muss vor dem Download laufen. Die README verweist auf das externe Repository github.com/WorldObservationLog/wrapper (README.md:30-32). Port und Health-Check-Endpoint:需要确认（nicht in den Quelldateien dokumentiert）.

Häufige Probleme und Lösungen

Problem 1: MP4Box nicht gefunden

Symptom: Fehlermeldung beim Start, dass MP4Box nicht gefunden wurde.

Lösung: MP4Box von der offiziellen GPac-Website herunterladen und zur PATH-Umgebungsvariable hinzufügen (README.md:1-3).

bash
1# Linux/macOS
2export PATH=$PATH:/pfad/zu/mp4box
3
4# Windows (PowerShell)
5$env:Path += ";C:\pfad\zu\mp4box"

Problem 2: Lyrics-Download schlägt fehl

Symptom: Fehlermeldung "failed to get lyrics" bei den meisten Songs.

Ursache: Falscher storefront in der Konfiguration. Der Storefront muss mit dem Apple Music Account übereinstimmen (config.yaml:49-53).

Lösung:

yaml
1# Für japanischen Account
2storefront: "jp"
3
4# Für US-Account
5storefront: "us"

Problem 3: Docker-Container startet nicht

Symptom: Container bricht sofort ab oder erstellt leeres Verzeichnis.

Ursache: config.yaml existiert nicht im aktuellen Verzeichnis. Docker erstellt bei nicht existierendem Mount-Pfad ein Verzeichnis statt einer Datei (README.md:63).

Lösung: Vor dem Docker-Befehl eine config.yaml erstellen oder die Standardkonfiguration aus dem Repository kopieren.

Problem 4: Speicherfehler bei großen Dateien

Symptom: "Out of memory" bei großen Alben oder Playlists.

Lösung: Die max-memory-limit-Einstellung in config.yaml anpassen (config.yaml:18):

yaml
1max-memory-limit: 512  # MB, erhöhen bei Bedarf

Nächste Schritte

Nach erfolgreicher Installation und Verifikation können folgende Funktionen genutzt werden:

1. Erweiterte Konfiguration: Anpassung der Dateinamen-Vorlagen und Ordnerstrukturen in config.yaml
2. Formatkonvertierung: Aktivierung der FFmpeg-Nachbearbeitung für kompatible Zielformate
3. Automatisierung: Skripterstellung für regelmäßige Downloads neuer Alben
4. Metadaten-Anpassung: Konfiguration der Tag-Formatierung für Musikbibliotheken

Für detaillierte Konfigurationsoptionen siehe die config.yaml-Dokumentation und die erweiterten Einstellungen für Konvertierung und Metadaten (config.yaml:54-66).