### Project Setup and Run

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Instructions for cloning the repository, installing dependencies, configuring the application, and running the main script. Assumes a Unix-like environment.

```shell
git clone https://github.com/WorldObservationLog/AppleMusicDecrypt.git
cd AppleMusicDecrypt
bash ./tools/install-deps.sh
poetry install
cp config.example.toml config.toml
poetry run python main.py
```

--------------------------------

### Install Dependencies and Setup AppleMusicDecrypt

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Clone the repository, navigate to the directory, install dependencies using the provided script and poetry, and copy the example configuration file.

```shell
git clone https://github.com/WorldObservationLog/AppleMusicDecrypt.git
cd AppleMusicDecrypt
bash ./tools/install-deps.sh   # installs gpac, MP4Box, mp4edit, ffmpeg
poetry install

cp config.example.toml config.toml
# Edit config.toml – at minimum set [instance] to a wrapper-manager endpoint

poetry run python main.py
```

--------------------------------

### Run WebAPI Demo

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Executes a demonstration function that showcases various `WebAPI` client methods for fetching music catalog data. This serves as an example of how to integrate and use the API.

```python
asyncio.run(demo())
```

--------------------------------

### Install and Run Telegram Bot

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Installs the Telegram bot with its specific dependencies and runs the bot. This requires editing the configuration file with bot credentials and user settings.

```shell
poetry install --with telegram_bot
cp extras/telegram_bot/config.example.toml extras/telegram_bot/config.toml
# Edit config.toml with bot token, allowed users, upload settings
poetry run python extras/telegram_bot/main.py
```

--------------------------------

### AppleMusicDecrypt Configuration Example

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

An annotated TOML configuration file for AppleMusicDecrypt, detailing settings for instance, local instance, region, download preferences, file naming, and metadata embedding.

```toml
# config.toml – annotated minimal production example

version = "0.0.10"   # must match CONFIG_VERSION in src/config.py

[instance]
# Remote wrapper-manager endpoint (public test instances maintained by the project)
url    = "wm.wol.moe"
secure = true          # use TLS

[localInstance]
# Optionally spin up wrapper-manager locally via QEMU
enable                    = false
enableHardwareAcceleration = false
memorySize                = "512M"
cpuModel                  = "Cascadelake-Server-v5"
startArgs                 = "-host 0.0.0.0 -port 32767 -debug"

[region]
language                = "en-US"   # metadata language for titles, artists, etc.
languageNotExistWarning = true

[download]
proxy          = ""            # optional HTTP/HTTPS proxy
parallelNum    = 4             # concurrent download streams
maxRunningTasks = 128
appleCDNIP     = ""            # pin to a regional Apple CDN IP for speed
codecAlternative = true        # fall back if requested codec is missing
codecPriority    = ["alac", "ec3", "ac3", "aac"]
atmosConventToM4a = true       # wrap EC3/AC3 in M4A container
failedSongNotPassIntegrityCheck = false

# File naming – Python format strings
songNameFormat         = "{disk}-{tracknum:02d} {title}"
dirPathFormat          = "downloads/{album_artist}/{album}"
playlistDirPathFormat  = "downloads/playlists/{playlistName}"
playlistSongNameFormat = "{playlistSongIndex:02d}. {artist} - {title}"

# Audio info suffix (ALAC only): e.g. " [ALAC][24bit][96.0kHz]"
audioInfoFormat = " [{codec}][{bit_depth}bit][{sample_rate_kHz}kHz]"

saveLyrics   = true
lyricsFormat = "lrc"        # "lrc" or "ttml"
lyricsExtra  = ["translation", "pronunciation"]
saveCover    = true
coverFormat  = "jpg"
coverSize    = "5000x5000"
maxSampleRate = 192000      # Hz – cap ALAC quality
maxBitDepth   = 24
afterDownloaded = ""        # shell command to run after each rip; {filename} placeholder

[metadata]
embedMetadata = ["title", "artist", "album", "album_artist", "composer",
                 "album_created", "genre", "created", "tracknum", "disk",
                 "lyrics", "cover", "copyright", "record_company",
                 "upc", "isrc", "rtng", "song_id", "album_id", "artist_id"]

```

--------------------------------

### Wrapper Manager Configuration

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Configuration examples for connecting to a public or locally deployed wrapper-manager instance for faster decryption without an Apple account or subscription.

```toml
[instance] # Mantainced by @WorldObservationLog
url = "wm.wol.moe"
secure = true
# or
[instance] # Mantainced by @itouakira
url = "wm1.wol.moe"
secure = true
```

--------------------------------

### Install AppleMusicDecrypt on Android via Termux

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Installs Termux and Debian, then sets up Poetry and installs AppleMusicDecrypt. This involves updating packages, installing dependencies, cloning the repository, and configuring the `config.toml` file.

```shell
# Step 1 – install Termux + Debian proot
pkg update && pkg install proot-distro
pd i debian
pd login debian

# Step 2 – install AppleMusicDecrypt
apt update && apt install pipx git -y
pipx install poetry && pipx ensurepath && source ~/.bashrc
git clone https://github.com/WorldObservationLog/AppleMusicDecrypt
cd AppleMusicDecrypt
bash ./tools/install-deps.sh
poetry env use /usr/bin/python3 && poetry install
cp config.example.toml config.toml
nano config.toml
```

--------------------------------

### Install Termux and Debian

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/android-deploy.md

Installs Termux and the Debian distribution using proot-distro. Ensure Termux has storage permissions.

```shell
pkg update && pkg install proot-distro
pd i debian
```

--------------------------------

### Copy Configuration File

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/extras/telegram_bot/README.md

Copy the example TOML configuration file to create your own configuration. Edit this file to set your Telegram API credentials, bot token, and local server URL.

```shell
cp extras/telegram_bot/config.example.toml extras/telegram_bot/config.toml
```

--------------------------------

### Deploy AppleMusicDecrypt in Debian

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/android-deploy.md

Clones the AppleMusicDecrypt repository, installs dependencies using Poetry, and configures the application. Remember to log into the Debian environment first.

```shell
apt update && apt install pipx git -y && pipx install poetry && pipx ensurepath && source ~/.bashrc
git clone https://github.com/WorldObservationLog/AppleMusicDecrypt
cd AppleMusicDecrypt
bash ./tools/install-deps.sh
poetry env use /usr/bin/python3 && poetry install
cp config.example.toml config.toml
nano config.toml
```

--------------------------------

### Launch and Manage Local QEMU Instance for Wrapper-Manager

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Boots a wrapper-manager QCOW2 image within QEMU and communicates via the QEMU Guest Agent (QGA). Automatically downloads the QCOW2 image if not present. Use for local testing and debugging.

```python
import asyncio
from src.qemu import QemuInstance

instance = QemuInstance()

async def demo(loop):
    # Downloads wrapper-manager.qcow2 automatically if not present in assets/
    await instance.launch_instance(loop)
    # Polls until wrapper-manager PID file appears → instance is ready

    # Read wrapper-manager log from inside the VM
    logs = await instance.logs()
    print(logs)

    # Graceful shutdown
    await instance.terminate()

loop = asyncio.new_event_loop()
loop.run_until_complete(demo(loop))
```

--------------------------------

### Configure Local QEMU Instance

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Configuration settings for running a local QEMU instance with KVM acceleration. Adjust memory, CPU, and startup arguments as needed for your environment.

```toml
[localInstance]
enable                    = true
enableHardwareAcceleration = true   # requires KVM on Linux or WHPX on Windows
hardwareAccelerator        = "kvm"
memorySize                 = "1G"
cpuModel                   = "Cascadelake-Server-v5"
showWindow                 = false
startArgs                  = "-host 0.0.0.0 -port 32767 -debug"
```

--------------------------------

### Inspect available audio qualities with 'qa'

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

The 'qa' command queries m3u8 manifests to display available audio streams and their technical parameters. Use flags to filter or invert the displayed columns.

```shell
# Syntax
qa [--invert] [--codec-id] [--codec] [--bitrate] [--average-bitrate]
   [--channels] [--sample-rate] [--bit-depth] [-b] URL [URL ...]
```

```shell
# Show all quality info for a playlist
> qa https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

```shell
# Show only Codec ID and Bit Depth (invert mode)
> qa --invert --codec-id --bit-depth https://music.apple.com/jp/song/caribbean-blue/339592231
```

```shell
# Hide codec-id column
> qa --codec-id https://music.apple.com/jp/album/nameless-name-single/1688539265
```

```shell
# Batch mode
> qa -b
https://music.apple.com/jp/song/caribbean-blue/339592231
https://music.apple.com/jp/album/nameless-name-single/1688539265
exit
```

--------------------------------

### Login to wrapper-manager with 'login'

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Use the 'login' command to authenticate an Apple ID with the wrapper-manager. This is necessary for self-hosted instances without pre-loaded accounts. It prompts for username, password, and optionally a 2FA code.

```shell
> login
Username: user@example.com
Password:             # hidden input
2FA code: 123456      # prompted only if two-factor authentication is required
# Output: Login Success!
```

--------------------------------

### Initialize and Use WrapperManager for Apple Music Operations

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Connects to a wrapper-manager gRPC server to handle decryption key negotiation, lyrics retrieval, m3u8 URL fetching, and Apple ID login/logout. Requires an active connection to the gRPC server.

```python
import asyncio
from src.grpc.manager import WrapperManager, WrapperManagerException

wm = WrapperManager()

async def demo():
    # Connect (insecure local or TLS remote)
    await wm.init("wm.wol.moe", secure=True)
    # await wm.init("127.0.0.1:8080", secure=False)

    # Check available regions / accounts
    status = await wm.status()
    print(status.ready)    # True if at least one account is logged in
    print(status.regions)  # ["jp", "us", "tw"]

    # Fetch lossless m3u8 URL for a song (requires logged-in account in song's region)
    m3u8_url = await wm.m3u8("1688539274")

    # Fetch time-synced lyrics
    lyrics_ttml = await wm.lyrics("1688539274", language="en-US", region="jp")

    # Login an Apple ID
    async def on_2fa(username, password):
        return input("2FA code: ")

    try:
        await wm.login("user@example.com", "password123", on_2fa)
    except WrapperManagerException as e:
        print(f"Login failed: {e.msg}")

    # Logout
    await wm.logout("user@example.com")

    # Decrypt a single sample (used internally by Ripper; key is an skd:// URI)
    await wm.decrypt(
        adam_id="1688539274",
        key="skd://key.apple.com/musickit/v1/....AlacStereo",
        sample=b"\x00\x01...",   # encrypted audio bytes
        sample_index=0
    )

asyncio.run(demo())
```

--------------------------------

### Download Multiple Items with Options

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Download multiple songs or albums with the same options by listing their URLs after the command and options. This avoids retyping the command for each item.

```shell
# Download multiple songs with the same options, without retyping the command
dl -c aac -l en-US -b
https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
https://music.apple.com/jp/album/nameless-name-single/1688539265
```

```shell
# Download multiple songs in one line
dl https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp https://music.apple.com/jp/album/nameless-name-single/1688539265
```

--------------------------------

### login

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Adds an Apple Account to the wrapper-manager, authenticating the Apple ID.

```APIDOC
## login — Add an Apple Account to wrapper-manager

### Description
Authenticates an Apple ID against the connected wrapper-manager instance. Required when using a self-hosted wrapper-manager with no pre-loaded accounts.

### Usage
```shell
login
```

### Interaction
```
> login
Username: user@example.com
Password:             # hidden input
2FA code: 123456      # prompted only if two-factor authentication is required
```

### Output
```
# Output: Login Success!
```
```

--------------------------------

### Android Configuration Overrides

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Recommended TOML configuration settings for Android deployment, specifying instance URL, download concurrency, and directory path formats for music and playlists.

```toml
[instance]
url    = "wm.wol.moe"
secure = true

[download]
parallelNum     = 2
maxRunningTasks = 4
dirPathFormat   = "/sdcard/Music/{album_artist}/{album}"
playlistDirPathFormat = "/sdcard/Music/playlists/{playlistName}"
```

--------------------------------

### Download with Specified Codec

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Specify the desired audio codec using the '-c' flag. Supported codecs include aac, ec3, ac3, and others.

```shell
# Download song/album with specified codec
dl -c aac https://music.apple.com/jp/song/caribbean-blue/339592231
```

--------------------------------

### Run AppleMusicDecrypt

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/android-deploy.md

Executes the main Python script of AppleMusicDecrypt using Poetry.

```shell
poetry run python main.py
```

--------------------------------

### Check Song Quality

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Use the 'quality' or 'qa' command to check the available audio quality options for a song or playlist. You can specify codec IDs to show or hide specific columns.

```shell
# Check the available quality of the song
quality https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

```shell
# Or a shorter command
qa https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

```shell
# You can hide a column by enabling it in the options.
qa --codec-id https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

```shell
# When you add --invert, it works the opposite way, showing the column for whichever option you enable.
qa --invert --codec-id https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

--------------------------------

### Check wrapper-manager region availability with 'status'

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

The 'status' command displays the storefronts (regions) that have active Apple accounts configured on the connected wrapper-manager instance.

```shell
> status
# Output: Regions available on wrapper-manager instance: jp, us, gb, tw
```

--------------------------------

### Fetch Playlist Info and Tracks with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves playlist details and all associated tracks, automatically handling pagination. Requires playlist ID, storefront, and language.

```python
    # Fetch playlist info and all tracks (auto-paginates)
    playlist = await api.get_playlist_info_and_tracks(
        "pl.u-Ympg5s39LRqp", storefront="jp", lang="en-US"
    )
```

--------------------------------

### Fetch Album Info with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves full album information, including all tracks, handling pagination for albums with more than 300 tracks. Specify album ID, storefront, and language.

```python
    # Fetch full album info (handles pagination for albums > 300 tracks)
    album = await api.get_album_info("1688539265", storefront="jp", lang="en-US")
    print(album.data[0].attributes.name)
    for track in album.data[0].relationships.tracks.data:
        print(track.id, track.attributes.name)
```

--------------------------------

### Download Song/Album with Default Codec (ALAC)

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Use the 'download' or 'dl' command to download songs or albums. The default codec is ALAC. Supports both song and album URLs.

```shell
# Download song/album with default codec (alac)
download https://music.apple.com/jp/album/nameless-name-single/1688539265
```

```shell
# Or a shorter command
dl https://music.apple.com/jp/album/nameless-name-single/1688539265
```

--------------------------------

### qa

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Inspects available audio qualities for a song, album, or playlist by querying the m3u8 manifest.

```APIDOC
## qa — Inspect Available Audio Qualities

### Description
Queries the m3u8 manifest for a song, album, or playlist and prints a table of all available codec streams with their technical parameters.

### Syntax
```shell
qa [--invert] [--codec-id] [--codec] [--bitrate] [--average-bitrate]
   [--channels] [--sample-rate] [--bit-depth] [-b] URL [URL ...]
```

### Parameters
- `--invert`: Inverts the logic of flags; flags shown are the *only* columns displayed.
- `--codec-id`: Shows the Codec ID column.
- `--codec`: Shows the Codec column.
- `--bitrate`: Shows the Bitrate column.
- `--average-bitrate`: Shows the Average Bitrate column.
- `--channels`: Shows the Channels column.
- `--sample-rate`: Shows the Sample Rate column.
- `--bit-depth`: Shows the Bit Depth column.
- `-b`: Enables batch mode for multiple URLs.
- `URL`: One or more Apple Music URLs.

### Examples
```shell
# Show all quality info for a playlist
> qa https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp

# Show only Codec ID and Bit Depth (invert mode)
> qa --invert --codec-id --bit-depth https://music.apple.com/jp/song/caribbean-blue/339592231

# Hide codec-id column
> qa --codec-id https://music.apple.com/jp/album/nameless-name-single/1688539265

# Batch mode
> qa -b
https://music.apple.com/jp/song/caribbean-blue/339592231
https://music.apple.com/jp/album/nameless-name-single/1688539265
exit
```

### Example Output
```
# Available audio qualities for song: Kessoku Band - Guitar, Loneliness, and Blue Planet
# +--------------------+--------+----------+-----------------+----------+-------------+-----------+
# | Codec ID           | Codec  | Bitrate  | Average Bitrate | Channels | Sample Rate | Bit Depth |
# +--------------------+--------+----------+-----------------+----------+-------------+-----------+
# | audio-alac-stereo  | alac   | 1411000  | 1411000         | 2/0/0    | 44100       | 16        |
# | audio-stereo       | aac    | 256000   | 256000          | 2/0/0    | None        | None      |
# +--------------------+--------+----------+-----------------+----------+-------------+-----------+
```
```

--------------------------------

### Download Songs, Albums, Artists, or Playlists using AppleMusicDecrypt

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Command-line syntax for downloading various Apple Music content types. Specify codec, language, and overwrite options as needed. Tasks run concurrently.

```shell
# Syntax
dl [-c CODEC] [-f] [-l LANGUAGE] [-b] [--include-participate-songs] URL [URL ...]

# Codec choices: alac (default), ec3, ac3, aac, aac-binaural, aac-downmix, aac-legacy
```

```shell
# Single song – lossless ALAC (default)
> dl https://music.apple.com/jp/album/nameless-name-single/1688539265?i=1688539274
```

```shell
# Album – Dolby Atmos
> dl -c ec3 https://music.apple.com/jp/album/nameless-name-single/1688539265
```

```shell
# Album – AAC, English metadata, force overwrite existing files
> dl -c aac -l en-US -f https://music.apple.com/jp/album/nameless-name-single/1688539265
```

```shell
# Artist – all albums
> dl https://music.apple.com/jp/artist/enya/160847
```

--------------------------------

### Run Telegram Bot Module

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/extras/telegram_bot/README.md

Execute the Telegram bot module from the project's root directory using Poetry. Ensure your configuration file is correctly set up before running.

```shell
poetry run python extras/telegram_bot/main.py
```

--------------------------------

### status

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Shows wrapper-manager Region Availability, printing storefronts with active Apple accounts.

```APIDOC
## status — Show wrapper-manager Region Availability

### Description
Prints the storefronts (regions) with active Apple accounts available on the connected wrapper-manager instance.

### Usage
```shell
status
```

### Output
```
# Output: Regions available on wrapper-manager instance: jp, us, gb, tw
```
```

--------------------------------

### Run and Update AppleMusicDecrypt on Android

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Commands to run the main Python script using Poetry and to update the project. Updates involve pulling the latest changes, updating Poetry dependencies, and reapplying configuration.

```shell
# Run
poetry run python main.py

# Update
git checkout -f && git pull
poetry update
cp config.example.toml config.toml && nano config.toml
```

--------------------------------

### Fetch Song Metadata with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves detailed information about a song using its ID and storefront. Includes attributes like name, artist, and enhanced HLS URL.

```python
import asyncio
from creart import it
from src.api import WebAPI

api = it(WebAPI)  # singleton managed by creart DI container

async def demo():
    # Fetch song metadata
    song = await api.get_song_info("1688539274", storefront="jp", lang="en-US")
    print(song.attributes.name)          # "名もなき何もかも"
    print(song.attributes.artistName)    # "トゲナシトゲアリ"
    print(song.attributes.extendedAssetUrls.enhancedHls)  # HLS m3u8 URL
```

--------------------------------

### Re-wrap Song Bytes with FFmpeg for Compatibility

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Uses FFmpeg to re-package the song bytes, ensuring broad player compatibility. This step may alter decoder configurations.

```python
song_bytes = fix_encapsulate(song_bytes)
```

--------------------------------

### Fetch Artist Songs with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves all song URLs for an artist, including those they are featured on. Requires artist ID, storefront, and language.

```python
    # Fetch all song URLs (including features) for an artist
    song_urls = await api.get_songs_from_artist("160847", storefront="jp", lang="en-US")
```

--------------------------------

### Build and Enrich Song Metadata

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Parses song and album data from Apple's API into a SongMetadata object, enriches it with cover art and lyrics, and sets audio properties like bit depth and sample rate. Use this to prepare metadata before serializing.

```python
from src.metadata import SongMetadata
from src.models.song_data import Datum
from src.models.album_meta import AlbumMeta

# Build from API objects
song_data: Datum = ...    # from WebAPI.get_song_info()
album_data: AlbumMeta = ...  # from WebAPI.get_album_info()

metadata = SongMetadata.parse_from_song_data(song_data)
metadata.parse_from_album_data(album_data)      # fills disk_total / track_total

# Enrich with cover image and lyrics
metadata.cover = b"..."   # JPEG bytes
metadata.set_lyrics("<tt:tt ...>")               # TTML string from wrapper-manager
metadata.set_playlist_index(3)                   # for playlist numbering
metadata.set_bit_depth_and_sample_rate(24, 96000)
```

--------------------------------

### Fetch Artist Albums with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves a list of all album URLs for a given artist, handling pagination and de-duplication. Requires artist ID, storefront, and language.

```python
    # Fetch all album URLs for an artist (paginated, de-duplicated)
    album_urls = await api.get_albums_from_artist("160847", storefront="jp", lang="en-US")
```

--------------------------------

### Logout from wrapper-manager with 'logout'

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

The 'logout' command removes an Apple Account from the wrapper-manager instance. Provide the username to log out.

```shell
> logout
Username: user@example.com
# Output: Logout Success!
```

--------------------------------

### WebAPI.get_playlist_info_and_tracks

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Fetches playlist details and all associated tracks from the Apple Music Catalog API, handling pagination.

```APIDOC
## `WebAPI.get_playlist_info_and_tracks`

### Description
Fetches the details of a playlist and all of its tracks. This method automatically handles pagination to retrieve all tracks, even for very large playlists.

### Method Signature
`async def get_playlist_info_and_tracks(playlist_id: str, storefront: str, lang: str)`

### Parameters
- **playlist_id** (str) - The unique identifier for the playlist.
- **storefront** (str) - The Apple Music storefront code (e.g., "jp").
- **lang** (str) - The desired language for the metadata (e.g., "en-US").

### Response
- Returns playlist information and a complete list of tracks within the playlist.

### Request Example
```python
playlist = await api.get_playlist_info_and_tracks(
    "pl.u-Ympg5s39LRqp", storefront="jp", lang="en-US"
)
```
```

--------------------------------

### WebAPI.get_album_info

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Fetches full album information, including tracks, from the Apple Music Catalog API.

```APIDOC
## `WebAPI.get_album_info`

### Description
Fetches comprehensive information for an album, including all its tracks. This method handles pagination for albums with more than 300 tracks.

### Method Signature
`async def get_album_info(album_id: str, storefront: str, lang: str)`

### Parameters
- **album_id** (str) - The unique identifier for the album.
- **storefront** (str) - The Apple Music storefront code (e.g., "jp").
- **lang** (str) - The desired language for the metadata (e.g., "en-US").

### Response
- Returns an album object containing details and a list of its tracks.

### Request Example
```python
album = await api.get_album_info("1688539265", storefront="jp", lang="en-US")
print(album.data[0].attributes.name)
for track in album.data[0].relationships.tracks.data:
    print(track.id, track.attributes.name)
```
```

--------------------------------

### Demux Encrypted MP4 into Sample List

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Processes raw encrypted MP4 data to extract individual audio samples and their metadata. Used after downloading the media from the m3u8 URI.

```python
raw_song: bytes = ...   # downloaded from m3u8_info.uri
song_info = extract_song(raw_song, codec=Codec.ALAC)
# song_info.samples → list[SampleInfo(descIndex, data, duration)]
# song_info.nhml    → NHML XML string for re-encapsulation
```

--------------------------------

### Download Album Art with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads album artwork in a specified format and size using the artwork URL. Requires the artwork URL, desired format, and size.

```python
    # Download album art
    cover_bytes = await api.get_cover(
        url=song.attributes.artwork.url,
        cover_format="jpg",
        cover_size="3000x3000"
    )
```

--------------------------------

### Check Song Existence with WebAPI

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Verifies if a specific song exists on a given Apple Music storefront. Requires song ID and storefront.

```python
    # Check existence on a storefront
    exists = await api.song_exist("1688539274", storefront="us")
```

--------------------------------

### Extract Media Information from M3U8 Manifest

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Parses an m3u8 manifest to extract media details, including the best codec stream, bit depth, and sample rate. Requires the m3u8 URL and desired codec.

```python
# Returns M3U8Info(uri, keys, codec_id, bit_depth, sample_rate)
m3u8_info = asyncio.run(extract_media(m3u8_url="https://...", codec="alac", task=task))
```

--------------------------------

### WebAPI.get_cover

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads album artwork from a given URL with specified format and size.

```APIDOC
## `WebAPI.get_cover`

### Description
Downloads album artwork from a provided URL, allowing specification of the desired image format and size.

### Method Signature
`async def get_cover(url: str, cover_format: str, cover_size: str)`

### Parameters
- **url** (str) - The URL of the artwork to download.
- **cover_format** (str) - The desired format for the downloaded image (e.g., "jpg").
- **cover_size** (str) - The desired dimensions for the artwork (e.g., "3000x3000").

### Response
- Returns the raw bytes of the downloaded cover image.

### Request Example
```python
cover_bytes = await api.get_cover(
    url=song.attributes.artwork.url, # Assuming 'song' object from get_song_info
    cover_format="jpg",
    cover_size="3000x3000"
)
```
```

--------------------------------

### Download songs and playlists from Apple Music

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Use the 'dl' command to download music. Supports various options for quality and language. Can download single URLs, multiple URLs, or use batch mode.

```shell
> dl --include-participate-songs https://music.apple.com/jp/artist/enya/160847
```

```shell
> dl https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

```shell
> dl -c alac -l en-US -b
https://music.apple.com/jp/album/nameless-name-single/1688539265
https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
exit
```

```shell
> dl https://music.apple.com/jp/album/nameless-name-single/1688539265 https://music.apple.com/jp/song/caribbean-blue/339592231
```

--------------------------------

### dl <URL1> <URL2> ...

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads multiple specified Apple Music URLs in a single command.

```APIDOC
## dl <URL1> <URL2> ...

### Description
Downloads multiple specified Apple Music URLs in a single command.

### Usage
```shell
dl <apple_music_url1> [<apple_music_url2> ...]
```

### Example
```shell
> dl https://music.apple.com/jp/album/nameless-name-single/1688539265 https://music.apple.com/jp/song/caribbean-blue/339592231
```
```

--------------------------------

### Configure AppleMusicDecrypt for Android

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/android-deploy.md

TOML configuration for AppleMusicDecrypt. Adjust instance details, download settings like parallel downloads and max running tasks, and specify directory formats for music and playlists.

```toml
[instance]
url = "wm.wol.moe" # Or use another wrapper-manager instance
secure = true

[download]
parallelNum = 2 # The recommended value is half of maxRunningTasks
maxRunningTasks = 4 # This value depends on the memory size of the device and is not recommended to be higher than 8
dirPathFormat = "/sdcard/Music/{album_artist}/{album}"
playlistDirPathFormat = "/sdcard/Music/playlists/{playlistName}"
```

--------------------------------

### Overwrite Existing Files

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Use the '-f' flag to force overwriting of existing files if they are already present.

```shell
# Overwrite existing files
dl -f https://music.apple.com/jp/song/caribbean-blue/339592231
```

--------------------------------

### dl -c alac -l en-US -b

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Enters batch mode for downloading multiple URLs, allowing specification of codec, locale, and other options. Type 'exit' to leave batch mode.

```APIDOC
## dl -c alac -l en-US -b

### Description
Enters batch mode for downloading multiple URLs. Allows specification of codec, locale, and other options. Type 'exit' to leave batch mode.

### Usage
```shell
dl [-c <codec>] [-l <locale>] -b
<url1>
<url2>
...
exit
```

### Example
```shell
> dl -c alac -l en-US -b
https://music.apple.com/jp/album/nameless-name-single/1688539265
https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
exit
```
```

--------------------------------

### Specify Metadata Language

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Set the language for song metadata using the '-l' flag followed by the language code (e.g., en-US).

```shell
# Specify song metadata language
dl -l en-US https://music.apple.com/jp/album/nameless-name-single/1688539265
```

--------------------------------

### Reassemble Decrypted Samples into Container

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Combines decrypted audio samples and reassembles them into a playable media container. Supports Atmos conversion.

```python
decrypted_media: bytes = b".".join(decrypted_samples)
song_bytes = encapsulate(song_info, decrypted_media, atmos_convent=True)
```

--------------------------------

### WebAPI.get_song_info

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Fetches detailed metadata for a specific song from the Apple Music Catalog API.

```APIDOC
## `WebAPI.get_song_info`

### Description
Fetches metadata for a specific song using its ID from the Apple Music Catalog API. Handles automatic token extraction and caching.

### Method Signature
`async def get_song_info(song_id: str, storefront: str, lang: str)`

### Parameters
- **song_id** (str) - The unique identifier for the song.
- **storefront** (str) - The Apple Music storefront code (e.g., "jp").
- **lang** (str) - The desired language for the metadata (e.g., "en-US").

### Response
- Returns a song object containing attributes like name, artistName, and extendedAssetUrls.

### Request Example
```python
song = await api.get_song_info("1688539274", storefront="jp", lang="en-US")
print(song.attributes.name)          # "名もなき何もかも"
print(song.attributes.artistName)    # "トゲナシトゲアリ"
print(song.attributes.extendedAssetUrls.enhancedHls)  # HLS m3u8 URL
```
```

--------------------------------

### Download Artist's All Albums/Songs

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Download all albums or songs by a specific artist by providing their Apple Music artist URL. Use '--include-participate-songs' to include songs the artist participated in.

```shell
# Download specify artist's all albums
dl https://music.apple.com/jp/artist/%E3%83%88%E3%82%B2%E3%83%8A%E3%82%B7%E3%83%88%E3%82%B2%E3%82%A2%E3%83%AA/1688539273
```

```shell
# Download specify artist's all songs
dl --include-participate-songs https://music.apple.com/jp/artist/%E3%83%88%E3%82%B2%E3%83%8A%E3%82%B7%E3%83%88%E3%82%B2%E3%82%A2%E3%83%AA/1688539273
```

--------------------------------

### dl

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads a specified Apple Music playlist.

```APIDOC
## dl

### Description
Downloads a specified Apple Music playlist.

### Usage
```shell
dl <apple_music_playlist_url>
```

### Example
```shell
> dl https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```
```

--------------------------------

### dl --include-participate-songs

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads all songs by a specified artist, including any featuring tracks.

```APIDOC
## dl --include-participate-songs

### Description
Downloads all songs by a specified artist, including any featuring tracks.

### Usage
```shell
dl --include-participate-songs <apple_music_artist_url>
```

### Example
```shell
> dl --include-participate-songs https://music.apple.com/jp/artist/enya/160847
```
```

--------------------------------

### Serialize Metadata to Mutagen Tags

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Converts the enriched SongMetadata object into a dictionary of mutagen tags, suitable for writing to audio files. Specify which metadata fields to include in the output.

```python
# Serialise to mutagen tag dict (used by write_metadata)
tags = metadata.to_mutagen_tags(embed_metadata=[
    "title", "artist", "album", "album_artist", "tracknum",
    "disk", "lyrics", "cover", "isrc", "upc", "rtng"
])
# tags == {"©nam": "Caribbean Blue", "©ART": "Enya", "trkn": ((1, 12),), ...
```

--------------------------------

### logout

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Removes an Apple Account from the wrapper-manager.

```APIDOC
## logout — Remove an Apple Account from wrapper-manager

### Description
Removes an Apple Account from the wrapper-manager.

### Usage
```shell
logout
```

### Interaction
```
> logout
Username: user@example.com
```

### Output
```
# Output: Logout Success!
```
```

--------------------------------

### Download Playlist Songs

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/README.md

Download all songs from a specified Apple Music playlist by providing the playlist URL.

```shell
# Download all songs of specified playlist
dl https://music.apple.com/jp/playlist/bocchi-the-rock/pl.u-Ympg5s39LRqp
```

--------------------------------

### Embed Metadata into Song Bytes

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Injects ID3 or MP4 tags into the song data using the mutagen library and MP4Box. Allows embedding metadata and cover art.

```python
song_bytes = write_metadata(song_bytes, metadata, embed_metadata=[...],
                            cover_format="jpg", params=song_info.params)
```

--------------------------------

### WebAPI.get_albums_from_artist

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves a list of all album identifiers associated with a given artist from the Apple Music Catalog API.

```APIDOC
## `WebAPI.get_albums_from_artist`

### Description
Fetches all album identifiers for a given artist from the Apple Music Catalog API. This method handles pagination and de-duplicates album entries.

### Method Signature
`async def get_albums_from_artist(artist_id: str, storefront: str, lang: str)`

### Parameters
- **artist_id** (str) - The unique identifier for the artist.
- **storefront** (str) - The Apple Music storefront code (e.g., "jp").
- **lang** (str) - The desired language for the metadata (e.g., "en-US").

### Response
- Returns a list of album URLs or identifiers associated with the artist.

### Request Example
```python
album_urls = await api.get_albums_from_artist("160847", storefront="jp", lang="en-US")
```
```

--------------------------------

### WebAPI.song_exist

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Checks if a specific song exists on a given Apple Music storefront.

```APIDOC
## `WebAPI.song_exist`

### Description
Checks for the existence of a specific song on a specified Apple Music storefront.

### Method Signature
`async def song_exist(song_id: str, storefront: str)`

### Parameters
- **song_id** (str) - The unique identifier for the song.
- **storefront** (str) - The Apple Music storefront code to check against (e.g., "us").

### Response
- Returns a boolean value: `True` if the song exists on the storefront, `False` otherwise.

### Request Example
```python
exists = await api.song_exist("1688539274", storefront="us")
```
```

--------------------------------

### Save Processed Audio and Metadata

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Saves the final processed audio bytes, cover image, and lyrics file to the configured directory structure. Specify the codec and metadata object. The `playlist` argument can be used for custom playlist path formatting.

```python
from src.save import save
from src.types import Codec

# Returns the absolute Path of the saved audio file
saved_path = save(
    song=song_bytes,          # final processed bytes
    codec=Codec.ALAC,
    metadata=metadata,
    playlist=None             # pass PlaylistInfo for playlist path/name formatting
)
# Creates: downloads/Enya/Paint the Sky with Stars/1-01 Caribbean Blue.m4a
#          downloads/Enya/Paint the Sky with Stars/cover.jpg   (if saveCover=true)
#          downloads/Enya/Paint the Sky with Stars/1-01 Caribbean Blue.lrc  (if saveLyrics=true)
print(saved_path)
# /home/user/AppleMusicDecrypt/downloads/Enya/Paint the Sky with Stars/1-01 Caribbean Blue.m4a
```

--------------------------------

### Rip an Album with Ripper

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Downloads an entire album from Apple Music. Tracks are processed concurrently. Specify codec and language flags.

```python
url = AppleMusicURL.parse_url("https://music.apple.com/jp/album/nameless-name-single/1688539265")
flags = Flags(language="ja")
asyncio.get_event_loop().run_until_complete(
    ripper.rip_album(url, codec="alac", flags=flags)
)
# Each track is dispatched as an independent async task; all run concurrently
# up to parallelNum download streams at a time.
```

--------------------------------

### WebAPI.get_songs_from_artist

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Retrieves a list of all song identifiers associated with an artist, including featured tracks, from the Apple Music Catalog API.

```APIDOC
## `WebAPI.get_songs_from_artist`

### Description
Fetches all song identifiers for a given artist from the Apple Music Catalog API, including songs where the artist is featured.

### Method Signature
`async def get_songs_from_artist(artist_id: str, storefront: str, lang: str)`

### Parameters
- **artist_id** (str) - The unique identifier for the artist.
- **storefront** (str) - The Apple Music storefront code (e.g., "jp").
- **lang** (str) - The desired language for the metadata (e.g., "en-US").

### Response
- Returns a list of song URLs or identifiers associated with the artist, including featured works.

### Request Example
```python
song_urls = await api.get_songs_from_artist("160847", storefront="jp", lang="en-US")
```
```

--------------------------------

### Verify Audio Integrity

Source: https://context7.com/worldobservationlog/applemusicdecrypt/llms.txt

Checks if the processed audio data can be decoded without errors, indicating successful decryption and container integrity. Issues a warning if the check fails.

```python
if not check_song_integrity(song_bytes):
    print("WARNING: audio integrity check failed – possible decryption error")
```

--------------------------------

### Update AppleMusicDecrypt

Source: https://github.com/worldobservationlog/applemusicdecrypt/blob/v2/android-deploy.md

Updates AppleMusicDecrypt within the Debian environment. This involves pulling the latest changes, updating Poetry dependencies, and reapplying configuration.

```shell
pd login debian
cd AppleMusicDecrypt
git checkout -f && git pull
poetry update
cp config.example.toml config.toml
nano config.toml
```