### First-Time Project Setup

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/PRE_COMMIT.md

Steps for cloning the Audiovault repository, installing pre-commit, and setting up frontend dependencies. Note the instruction to skip `pre-commit install`.

```bash
git clone https://github.com/Bl4nk44/Audiovault.git
cd Audiovault
pip install pre-commit
# Don't run pre-commit install — see note above
npm --prefix frontend install
```

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

### Standard Docker Compose Setup

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/CONFIGURATION.md

Initializes the Audiovault environment by copying the example .env file and starting services with Docker Compose.

```bash
cp .env.example .env
# Edit .env: set ADMIN_PASSWORD and JWT_SECRET_KEY at minimum
docker compose up -d --build
```

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

### Clone and Setup Audiovault Project

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

Steps to fork, clone the repository, configure environment variables, and start the project using Docker Compose.

```bash
git clone https://github.com/your-username/Audiovault.git
cd Audiovault
git remote add upstream https://github.com/Bl4nk44/Audiovault.git

cp .env.example .env

docker compose up -d --build
```

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

### Tailscale Network Setup

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Instructions for installing and configuring Tailscale for secure remote access to Audiovault.

```bash
# Install Tailscale on host
curl -fsSL https://tailscale.com/install.sh | sh

# Authenticate
sudo tailscale up

# Get your Tailscale IP
tailscale ip -4

# Access from anywhere: http://[your-tailscale-ip]:2137
```

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

### Docker Compose Setup for Audiovault

Source: https://context7.com/bl4nk44/audiovault/llms.txt

This snippet outlines the steps to clone the Audiovault repository, configure the .env file with essential credentials, and start all services using Docker Compose. It also includes commands to verify container status and tail backend logs.

```bash
git clone https://github.com/Bl4nk44/Audiovault.git
cd Audiovault
cp .env.example .env
# Edit .env — minimum required fields:
#   ADMIN_PASSWORD=YourSecurePassword
#   JWT_SECRET_KEY=$(openssl rand -hex 32)
#   DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/audiovault
#   REDIS_URL=redis://redis:6379/0

docker compose up -d --build

docker compose ps
# EXPECTED: db, redis, backend (port 8000), frontend (port 2137) all Up

docker compose logs -f backend
```

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

### Build and Start Audiovault Containers

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

Build the Docker images and start all Audiovault services in detached mode. Allow approximately 30 seconds for the services to initialize.

```bash
docker compose up -d --build

# Wait ~30 seconds for startup...

# Check status
docker compose ps
```

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

### Example .env Security Configuration

Source: https://github.com/bl4nk44/audiovault/blob/main/SECURITY.md

Demonstrates secure and insecure examples of environment variable configurations, highlighting the importance of strong, unique passwords.

```bash
# ✅ Good - Strong, random password
ADMIN_PASSWORD=Tr0p!c@lL!m0n_K3y$uP3r#Secure_2024

# ❌ Bad - Weak and exposed
ADMIN_PASSWORD=admin123
```

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

### Build and Start Audiovault Docker Containers

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Build the Docker images and start the Audiovault services in the background. Use `docker compose ps` to check if containers are running and `docker compose logs` to view startup output.

```bash
# Build and start containers in background
docker compose up -d --build

# Check if containers are running
docker compose ps

# View startup logs
docker compose logs -f backend
docker compose logs -f frontend
```

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

### Install and Run Pre-commit Hooks

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

Install the pre-commit package and run all configured hooks to check code quality and style before committing. Note potential conflicts with global hooks.

```bash
pip install pre-commit
pre-commit run --all-files
```

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

### Check Docker Installation

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

Verify that Docker and Docker Compose are installed on your system before proceeding.

```bash
docker --version
docker compose --version
```

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

### Start Audiovault with Docker Compose

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/GETTING_STARTED.md

Build and start the Audiovault containers in the background using Docker Compose. This command ensures all services are running.

```bash
# Build and start containers in background
docker compose up -d --build
```

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

### Install Pre-Commit

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/PRE_COMMIT.md

Install the pre-commit package using pip. Avoid running `pre-commit install` globally due to potential conflicts with other git hooks.

```bash
pip install pre-commit
```

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

### Install Frontend Dependencies

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/PRE_COMMIT.md

Install Node.js dependencies for the frontend using npm. This is required for frontend linters like ESLint to function correctly.

```bash
npm --prefix frontend install
```

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

### Basic Docker Compose Setup (SQLite)

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

A minimal Docker Compose configuration for Audiovault using SQLite for the database.

```yaml
version: "3.8"

services:
  backend:
    image: audiovault:latest
    ports:
      - "8000:8000"
    volumes:
      - ./music_library:/app/music_library
      - ./data:/app/data
    environment:
      - DATABASE_URL=sqlite:///./data/audiovault.db
      - FIRST_SUPERUSER_EMAIL=admin@example.com
      - FIRST_SUPERUSER_PASSWORD=YourPassword123!
    restart: unless-stopped

  frontend:
    image: audiovault-frontend:latest
    ports:
      - "2137:80"
    environment:
      - BACKEND_URL=http://backend:8000
    depends_on:
      - backend
    restart: unless-stopped
```

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

### Configure Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Copy the example environment file and edit it with your specific settings. This file contains crucial configuration options for Audiovault.

```bash
# Copy the example environment file
cp .env.example .env

# Edit the .env file with your preferred settings
nano .env
```

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

### Verify yt-dlp Installation

Source: https://github.com/bl4nk44/audiovault/blob/main/SUPPORT.md

Command to check if `yt-dlp` is installed and accessible within the backend container. This is a common step when troubleshooting download issues.

```bash
docker compose exec backend yt-dlp --version
```

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

### Clone Audiovault Repository and Configure Environment

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

Clone the Audiovault repository, navigate into the directory, and copy the example environment file. Ensure you set a secure ADMIN_PASSWORD in the .env file.

```bash
git clone https://github.com/Bl4nk44/Audiovault.git
cd Audiovault

cp .env.example .env

# REQUIRED: Set your admin password in .env
# nano .env -> ADMIN_PASSWORD=your_secure_password
```

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

### Configure Environment Variables

Source: https://github.com/bl4nk44/audiovault/blob/main/README.md

Copy the example environment file and rename it to .env. This file is used to store secrets and configurations.

```bash
cp .env.example .env
```

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

### Python Async Function Example

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

An example of an asynchronous Python function using type hints and SQLAlchemy ORM for database interaction.

```python
async def get_track(track_id: int) -> Track | None:
    result = await db.execute(select(Track).where(Track.id == track_id))
    return result.scalar_one_or_none()
```

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

### Manage Audiovault Docker Containers

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Common Docker commands for viewing logs, stopping, starting, and restarting Audiovault containers.

```bash
# View logs
docker compose logs backend
docker compose logs -f backend  # Follow in real-time

# Stop/Start containers
docker compose stop
docker compose start

# Restart containers
docker compose restart backend

# Update and restart
docker compose pull
docker compose up -d
```

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

### Get Album Cover Art

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Fetches the cover art for a given album ID.

```bash
curl -s "http://localhost:8000/api/v1/stream/album/9a1b2c3d-4e5f-6789-abcd-ef0123456789/cover" \
  --output album_cover.jpg
```

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

### Example Commit Message Format

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

Demonstrates the Conventional Commits format for Git commit messages, including type, scope, and description.

```git
feat(spotify): add playlist import
fix(auth): resolve JWT expiration handling
docs: update installation guide
chore(deps): bump ruff to 0.15
```

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

### Production Docker Compose Setup (PostgreSQL + Redis)

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

A robust Docker Compose configuration for Audiovault using PostgreSQL and Redis for production environments.

```yaml
version: "3.8"

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: audiovault
      POSTGRES_USER: audiovault
      POSTGRES_PASSWORD: SecurePassword123!
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7
    command: redis-server --requirepass SecurePassword123!
    volumes:
      - redis_data:/data
    restart: unless-stopped

  backend:
    image: audiovault:latest
    ports:
      - "8000:8000"
    volumes:
      - ./music_library:/app/music_library
    environment:
      - DATABASE_URL=postgresql+asyncpg://audiovault:SecurePassword123!@postgres:5432/audiovault
      - REDIS_URL=redis://:SecurePassword123!@redis:6379/0
      - USE_REDIS=true
      - WORKERS=4
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  frontend:
    image: audiovault-frontend:latest
    ports:
      - "2137:80"
    environment:
      - BACKEND_URL=http://backend:8000
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
```

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

### Check Audiovault Container Status

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/GETTING_STARTED.md

Verify that all Audiovault containers are running correctly after starting them with Docker Compose.

```bash
docker compose ps
```

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

### Example Branch Naming Conventions

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

Illustrates common conventions for naming Git branches based on the type of change being introduced.

```git
feature/add-spotify-sync
fix/auth-token-refresh
docs/update-readme
refactor/simplify-api-calls
chore/update-dependencies
```

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

### Check System Dependencies with Docker

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Verify that Docker and Docker Compose are installed and meet the minimum version requirements. Also, check available disk space and RAM.

```bash
# Check Docker installation
docker --version
docker compose --version

# Check available disk space
df -h  # Linux/macOS
dir    # Windows

# Check RAM
free -h           # Linux
vm_stat           # macOS
SystemInfo        # Windows
```

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

### Restart Audiovault After Cleanup

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

After stopping and removing existing containers, use this command to rebuild and start Audiovault services in detached mode.

```bash
docker compose up -d
```

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

### Check Audiovault Container Logs

Source: https://github.com/bl4nk44/audiovault/blob/main/SUPPORT.md

Use these commands to check the logs of the backend and frontend containers when Docker compose fails to start. This helps in diagnosing startup issues.

```bash
docker compose logs backend
docker compose logs frontend
```

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

### Get Library Folder Structure

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieve the folder structure of the download library, showing available sources and playlists.

```bash
curl -s http://localhost:8000/api/v1/downloads/library/folders \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Configure Frontend Backend URL

Source: https://github.com/bl4nk44/audiovault/blob/main/SUPPORT.md

Example of setting the `BACKEND_URL` environment variable in `docker-compose.yml` for the frontend to connect to the backend. Ensure this matches your backend service name and port.

```yaml
frontend:
  environment:
    - BACKEND_URL=http://audiovault-backend:8000
```

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

### Set Admin Password in .env

Source: https://github.com/bl4nk44/audiovault/blob/main/README.md

For enhanced security, set a strong ADMIN_PASSWORD in your .env file before starting Audiovault. If not set, a random password will be generated but not displayed in logs.

```bash
ADMIN_PASSWORD=your_secure_password
```

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

### Get Last.fm Recommendations

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Fetches personalized track recommendations based on your Last.fm listening history. Use `force_refresh=true` to re-evaluate history.

```bash
curl -s "http://localhost:8000/api/v1/lastfm/recommendations?force_refresh=false&source=auto" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Configure Backend Memory Limit

Source: https://github.com/bl4nk44/audiovault/blob/main/SUPPORT.md

Example of increasing the memory limit for the backend service in `docker-compose.yml`. This can help resolve UI responsiveness or performance issues.

```yaml
services:
  backend:
    mem_limit: 4g  # Increase from 2g if needed
```

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

### Get and Update User Settings

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the current user's settings or updates them. Settings include client IDs, download paths, and theme preferences.

```bash
# Get current settings
curl -s http://localhost:8000/api/v1/settings/ \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Login to Audiovault API and get JWT tokens

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Authenticates a user and returns JWT access and refresh tokens. This endpoint is rate-limited to 10 requests per minute. The access token should be stored for subsequent authenticated requests.

```bash
curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "Secret123!"}' | jq

# Expected response (200 OK):
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "bearer"
# }

# Store the token for subsequent requests:
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"Secret123!"}' | jq -r .access_token)
```

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

### TypeScript React Component Example

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

A basic example of a functional React component in TypeScript, adhering to strict typing and using props.

```typescript
interface TrackCardProps {
  trackId: string;
  onSelect: (id: string) => void;
}

export const TrackCard = ({ trackId, onSelect }: TrackCardProps) => (
  <div onClick={() => onSelect(trackId)}>{/* content */}</div>
);
```

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

### Database Configuration Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Set up database connection URLs for SQLite, PostgreSQL, and PostgreSQL with asyncpg.

```bash
# SQLite (default, simplest setup)
DATABASE_URL=sqlite:///./audiovault.db

# PostgreSQL (recommended for production)
DATABASE_URL=postgresql://audiovault:password@postgres:5432/audiovault

# PostgreSQL with asyncpg (faster)
DATABASE_URL=postgresql+asyncpg://audiovault:password@postgres:5432/audiovault
```

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

### View Audiovault Startup Logs

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/GETTING_STARTED.md

Monitor the startup process of the Audiovault backend and frontend services by viewing their logs in real-time.

```bash
docker compose logs -f backend
docker compose logs -f frontend
```

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

### Get current authenticated user details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the full UserResponse object for the currently authenticated user by passing the Bearer token in the Authorization header. This endpoint is used to verify the token and get user information.

```bash
curl -s http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN" | jq
# Returns full UserResponse object
```

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

### Clone Audiovault Repository and Navigate

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Clone the Audiovault project from GitHub and change the directory to the project root.

```bash
git clone https://github.com/Bl4nk44/Audiovault.git
cd Audiovault
```

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

### Database & Storage Environment Variables

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/CONFIGURATION.md

Set up database connection URLs and storage settings via environment variables. PostgreSQL is required for production.

```bash
# PostgreSQL (required — no SQLite in production)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/audiovault
# Redis
REDIS_URL=redis://redis:6379/0

# Storage
DOWNLOAD_DIR=/downloads
MAX_PARALLEL_DOWNLOADS=3
STORAGE_QUOTA_GB=500
```

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

### Get current user

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the details of the currently authenticated user.

```APIDOC
## GET /api/v1/auth/me

### Description
Retrieves the details of the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/me

### Headers
- **Authorization**: Bearer <your_access_token>

### Response
#### Success Response
Returns the full UserResponse object for the authenticated user.
```

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

### Get album cover art

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the cover art for a specified album.

```APIDOC
## GET /api/v1/stream/album/{album_id}/cover

### Description
Retrieves the cover art for a given album.

### Method
GET

### Endpoint
/api/v1/stream/album/{album_id}/cover

### Parameters
#### Path Parameters
- **album_id** (string) - Required - The identifier for the album.

### Response
#### Success Response (200)
Returns the album cover art image (e.g., `image/jpeg`).
```

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

### Storage Configuration Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Configure the music library path, maximum upload size, and concurrent downloads.

```bash
# Music library storage path
MUSIC_LIBRARY_PATH=/path/to/music/library

# Maximum file size for uploads (in MB)
MAX_UPLOAD_SIZE=500

# Concurrent downloads allowed
CONCURRENT_DOWNLOADS=3
```

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

### Get track cover art

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the cover art for a given track.

```APIDOC
## GET /api/v1/stream/{track_id}/cover

### Description
Fetches the cover art for a specified track. The system prioritizes local cover files, then embedded art, and finally external album art URLs.

### Method
GET

### Endpoint
/api/v1/stream/{track_id}/cover

### Parameters
#### Path Parameters
- **track_id** (string) - Required - The identifier for the track.

### Response
#### Success Response (200)
Returns the cover art image (e.g., `image/jpeg` or `image/png`).
```

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

### Integration Environment Variables

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/CONFIGURATION.md

Configure optional integrations like Spotify, Last.fm, and Genius using their respective API keys and tokens.

```bash
# Spotify (optional — built-in anonymous fallback works out of the box)
# See SPOTIFY_INTEGRATION.md for full details
SPOTIFY_CLIENT_ID=your_client_id          # Override embedded credentials
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_SP_DC=your_sp_dc_cookie_value     # Free account cookie (~1yr TTL)
SPOTIFY_HOST_PROXY=http://host.docker.internal:8765  # Host proxy for embed scraping

# Last.fm — see LASTFM_INTEGRATION.md
LASTFM_API_KEY=your_lastfm_api_key
LASTFM_API_SECRET=your_lastfm_api_secret

# Genius (lyrics)
GENIUS_API_TOKEN=your_genius_api_token
```

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

### Subsonic Playlist Operations - Get All

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves a list of all playlists available in the Subsonic server.

```bash
# Get all playlists
curl -s "$BASE/getPlaylists.view?$CREDS" | jq
```

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

### Register a new user with Audiovault API

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Demonstrates how to register a new user account via the Audiovault API. This endpoint is rate-limited to 5 requests per minute. Ensure the Content-Type is set to application/json.

```bash
curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "email": "alice@example.com", "password": "Secret123!"}' | jq

# Expected response (201 Created):
# {
#   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
#   "username": "alice",
#   "email": "alice@example.com",
#   "is_active": true,
#   "created_at": "2025-01-15T10:00:00Z"
# }
```

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

### Playlist Management API - Get Playlist

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves a single playlist, including its tracks.

```APIDOC
## GET /api/v1/playlists/{id}

### Description
Retrieves a specific playlist by its ID, including all its tracks.

### Method
GET

### Endpoint
/api/v1/playlists/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the playlist.
```

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

### Set Essential Audiovault Configuration

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Configure essential variables in the `.env` file, including admin credentials and streaming service API keys. Remember to change the default password.

```bash
# Admin access
FIRST_SUPERUSER_EMAIL=admin@example.com
FIRST_SUPERUSER_PASSWORD=SecurePassword123!  # Change this!

# Streaming service credentials (add as needed)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_secret
YOUTUBE_API_KEY=your_youtube_api_key
```

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

### Spotify API - Get Album Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific album on Spotify.

```APIDOC
## GET /api/v1/spotify/album/{id}

### Description
Retrieves detailed information about a specific Spotify album.

### Method
GET

### Endpoint
/api/v1/spotify/album/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify ID of the album.
```

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

### YouTube Integration Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Configure YouTube API key, Invidious proxy settings, and preferred video quality.

```bash
# Get API key: https://console.cloud.google.com/
YOUTUBE_API_KEY=your_api_key

# Use Invidious proxy to bypass regional restrictions
YOUTUBE_PROXY_ENABLED=true
YOUTUBE_PROXY_URL=https://invidious.example.com

# Preferred video quality (22=720p, 18=360p)
YTDLP_FORMAT=22
```

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

### Spotify API - Get Artist Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific artist on Spotify.

```APIDOC
## GET /api/v1/spotify/artist/{id}

### Description
Retrieves detailed information about a specific Spotify artist.

### Method
GET

### Endpoint
/api/v1/spotify/artist/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify ID of the artist.
```

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

### Spotify API - Get Playlist Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific playlist on Spotify.

```APIDOC
## GET /api/v1/spotify/playlist/{id}

### Description
Retrieves detailed information about a specific Spotify playlist.

### Method
GET

### Endpoint
/api/v1/spotify/playlist/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify ID of the playlist.
```

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

### Spotify API - Get Track Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific track on Spotify.

```APIDOC
## GET /api/v1/spotify/track/{id}

### Description
Retrieves detailed information about a specific Spotify track.

### Method
GET

### Endpoint
/api/v1/spotify/track/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify ID of the track.
```

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

### Configure Spotify Integration Credentials

Source: https://github.com/bl4nk44/audiovault/blob/main/SUPPORT.md

Environment variables to set in `.env` for Spotify integration. Ensure these client ID and secret are correctly obtained from the Spotify Developer Dashboard.

```bash
SPOTIFY_CLIENT_ID=your_id
SPOTIFY_CLIENT_SECRET=your_secret
```

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

### Get Library Folder Structure

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the folder structure of the download library, categorized by source.

```APIDOC
## GET /api/v1/downloads/library/folders

### Description
Retrieves the folder structure of the download library, showing playlists organized by source.

### Method
GET

### Endpoint
/api/v1/downloads/library/folders
```

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

### Subsonic Authentication - Legacy and Token

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Demonstrates how to construct credentials for Subsonic API authentication, showing both legacy password-based and preferred token-based methods.

```bash
# Legacy auth (password in plain or hex)
BASE="http://localhost:8000/rest"
CREDS="u=admin&p=YourPassword&v=1.16.1&c=MyApp&f=json"

# Token auth (preferred): t=md5(password+salt), s=random_salt
SALT="randomsalt"
TOKEN=$(echo -n "YourPassword${SALT}" | md5sum | awk '{print $1}')
CREDS="u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=MyApp&f=json"
```

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

### Configure Last.fm API Credentials in .env

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/LASTFM_INTEGRATION.md

Add your Last.fm API Key and Shared Secret to the .env file in your Audiovault root directory. Ensure these are the correct credentials obtained from Last.fm.

```bash
# Last.fm Integration
LASTFM_API_KEY=your_copied_api_key
LASTFM_API_SECRET=your_copied_shared_secret
```

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

### Get and update user settings

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the current user settings or updates them via a POST request.

```APIDOC
## GET|POST /api/v1/settings/

### Description
Allows retrieval of current user settings using a GET request, or updating settings using a POST request with a JSON payload.

### Method
GET, POST

### Endpoint
/api/v1/settings/

### Request Body (for POST)
- **spotifyClientId** (string) - Optional - Spotify API client ID.
- **spotifyClientSecret** (string) - Optional - Spotify API client secret.
- **youtubeApiKey** (string) - Optional - YouTube API key.
- **downloadPath** (string) - Optional - Path for downloaded files.
- **maxParallelDownloads** (integer) - Optional - Maximum concurrent downloads.
- **theme** (string) - Optional - UI theme (e.g., 'dark', 'light').
- **language** (string) - Optional - UI language (e.g., 'en').
- **filenameSchema** (string) - Optional - Schema for naming downloaded files.
- **audioQuality** (string) - Optional - Desired audio quality (e.g., 'high', 'medium').

### Request Example
```bash
# Get current settings
curl -s http://localhost:8000/api/v1/settings/ \
  -H "Authorization: Bearer $TOKEN" | jq
```

### Response
#### Success Response (200)
Returns a JSON object containing the user's current settings.
```

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

### Get / update current user

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the current user's profile information or updates their username.

```APIDOC
## GET|PUT /api/v1/users/me

### Description
Allows retrieval of the current user's profile information using a GET request, or updating the user's username using a PUT request with a JSON payload.

### Method
GET, PUT

### Endpoint
/api/v1/users/me

### Request Body (for PUT)
- **username** (string) - Required - The new username for the user.

### Request Example
```bash
# Get profile
curl -s http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN" | jq

# Update username
curl -s -X PUT http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice_new"}' | jq
```

### Response
#### Success Response (200)
For GET: Returns user profile data. For PUT: Returns status indicating success.
```

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

### Audiovault .env Configuration Reference

Source: https://context7.com/bl4nk44/audiovault/llms.txt

A comprehensive reference for all configuration variables in the .env file, covering database, cache, admin credentials, JWT settings, storage, networking, and optional integrations.

```bash
# Database & Cache
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/audiovault
REDIS_URL=redis://redis:6379/0

# Admin (required on first run)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=SecurePassword123!

# JWT
JWT_SECRET_KEY=<openssl rand -hex 32>
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# Storage
DOWNLOAD_DIR=/downloads
MAX_PARALLEL_DOWNLOADS=3
STORAGE_QUOTA_GB=500

# Networking
ALLOWED_HOSTS=localhost,audiovault.example.com
BACKEND_CORS_ORIGINS=["http://localhost:2137","https://audiovault.example.com"]

# Integrations (all optional)
SPOTIFY_CLIENT_ID=         # Override embedded anonymous credentials
SPOTIFY_CLIENT_SECRET=
SPOTIFY_SP_DC=             # sp_dc cookie for richer Spotify access (~1yr TTL)
LASTFM_API_KEY=
LASTFM_API_SECRET=
GENIUS_API_TOKEN=

# Misc
LOG_LEVEL=INFO
TIMEZONE=UTC
```

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

### Get Last.fm profile & friends

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Fetches the user's Last.fm profile information and a list of their friends.

```APIDOC
## GET /api/v1/lastfm/profile

### Description
Retrieves the user's Last.fm profile data and their friends list.

### Method
GET

### Endpoint
/api/v1/lastfm/profile

### Response
#### Success Response (200)
Returns a JSON object containing 'user' profile data and a 'friends' array.
```

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

### Get Last.fm Profile and Friends

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves your Last.fm profile information and a list of your friends. Requires authentication.

```bash
curl -s "http://localhost:8000/api/v1/lastfm/profile" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Get Single Playlist with Tracks

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves a specific playlist, including its tracks, using its unique ID.

```bash
# Get single playlist with tracks
PL_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
curl -s "http://localhost:8000/api/v1/playlists/$PL_ID" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Import Playlist from URL

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Accepts URLs from various music streaming services. Returns extracted metadata for preview before queuing downloads.

```bash
# Import a Spotify playlist
curl -s -X POST http://localhost:8000/api/v1/import/playlist \
  -H "Content-Type: application/json" \
  -d '{"url": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"}' | jq
```

```bash
# Import a YouTube Music playlist
curl -s -X POST http://localhost:8000/api/v1/import/playlist \
  -H "Content-Type: application/json" \
  -d '{"url": "https://music.youtube.com/playlist?list=PLx0sYbCqOb8TBPRdmBHs5Iftvv9TPboYG"}' | jq
```

```bash
# Import a SoundCloud playlist
curl -s -X POST http://localhost:8000/api/v1/import/playlist \
  -H "Content-Type: application/json" \
  -d '{"url": "https://soundcloud.com/user/sets/my-playlist"}' | jq
```

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

### Run Frontend Tests and Linting

Source: https://github.com/bl4nk44/audiovault/blob/main/CONTRIBUTING.md

Execute frontend tests and linting using npm commands within the Docker environment.

```bash
docker compose exec frontend npm test

docker compose exec frontend npm run lint
```

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

### Configure YouTube API Key

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Generate a YouTube Data API v3 key from the Google Cloud Console and add it to your `.env` file. Restart the backend service after updating.

```bash
YOUTUBE_API_KEY=your_api_key

# Restart backend: `docker compose restart backend`
```

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

### Create a New Playlist

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Creates a new playlist with a specified name, comment, and public status. Returns a PlaylistResponse object.

```bash
# Create playlist
curl -s -X POST http://localhost:8000/api/v1/playlists/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Road Trip", "comment": "Summer 2025", "public": false}' | jq
# Returns PlaylistResponse with id, name, tracks_count, tracks[]
```

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

### Spotify Integration Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Provide Spotify API credentials and cache expiration time.

```bash
# Get credentials: https://developer.spotify.com/dashboard
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_CACHE_EXPIRE_MINUTES=60
```

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

### Get Download Queue

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves the current download queue, including items that are pending, downloading, or processing, along with their progress.

```APIDOC
## GET /api/v1/downloads/queue

### Description
Returns a list of items currently in the download queue, showing their status and progress.

### Method
GET

### Endpoint
/api/v1/downloads/queue
```

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

### Configure Spotify Credentials

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

Obtain Spotify Client ID and Client Secret from the Spotify Developer Dashboard and add them to your `.env` file. Restart the backend service after updating.

```bash
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_secret

# Restart backend: `docker compose restart backend`
```

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

### File and Folder Permissions Management

Source: https://github.com/bl4nk44/audiovault/blob/main/SECURITY.md

Illustrates how to set secure file and folder permissions using chmod and chown commands to protect sensitive files and restrict access.

```bash
# Protect sensitive files
chmod 600 .env
chmod 755 ./music_library

# Ensure only root can read
chown root:root /path/to/config
```

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

### Stop and Remove Audiovault Containers

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

Completely stop and remove all Audiovault containers, networks, and volumes. This is useful for cleaning up or starting fresh.

```bash
docker compose down
```

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

### Subsonic Playlist Operations - Get Specific

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Fetches the tracks contained within a specific playlist. Requires the playlist's UUID.

```bash
# Get specific playlist tracks
curl -s "$BASE/getPlaylist.view?id=<playlist-uuid>&$CREDS" | jq
```

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

### Scan Directory for MP3s

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Scan a specified download directory for existing MP3 files and register them in the database. This is useful for importing pre-existing music.

```bash
curl -s -X POST "http://localhost:8000/api/v1/downloads/maintenance/scan-library" \
  -H "Authorization: Bearer $TOKEN" | jq
# Scans DOWNLOAD_DIR and registers existing files in the database
```

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

### Check Audiovault Logs

Source: https://github.com/bl4nk44/audiovault/blob/main/QUICKSTART.md

If you encounter issues accessing Audiovault, check the logs for the backend service to identify potential problems.

```bash
docker compose logs backend
```

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

### Get and Update User Profile

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Allows fetching the current user's profile information or updating their username. Requires authentication.

```bash
# Get profile
curl -s http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN" | jq
```

```bash
# Update username
curl -s -X PUT http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice_new"}' | jq
```

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

### Update Audiovault Settings

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Use this endpoint to configure various settings for Audiovault, including download parallelism, audio quality, filename schema, and theme.

```bash
curl -s -X POST http://localhost:8000/api/v1/settings/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maxParallelDownloads": 5,
    "audioQuality": "lossless",
    "filenameSchema": "{artist}/{album}/{title}",
    "theme": "light"
  }' | jq
```

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

### Get Last.fm Connection URL

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Generates the OAuth URL required to connect a Last.fm account. This URL should be opened in a browser for authorization.

```bash
curl -s "http://localhost:8000/api/v1/lastfm/connect" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Get Spotify Album Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific Spotify album using its ID. Requires an Authorization Bearer token.

```bash
# Album
curl -s "http://localhost:8000/api/v1/spotify/album/0bCAjihnp0OTJjnB2zkGUF" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Get Spotify Artist Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific Spotify artist using their ID. Requires an Authorization Bearer token.

```bash
# Artist
curl -s "http://localhost:8000/api/v1/spotify/artist/4tZwfgrHOc3mvqYlEYSvVi" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Restart All Failed/Cancelled Downloads

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Initiate a restart for all downloads that are currently in a failed or cancelled state.

```bash
curl -s -X POST http://localhost:8000/api/v1/downloads/restart-all \
  -H "Authorization: Bearer $TOKEN" | jq
# {"status":"success","count":4}
```

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

### Get Spotify Playlist Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific Spotify playlist using its ID. Requires an Authorization Bearer token.

```bash
# Playlist
curl -s "http://localhost:8000/api/v1/spotify/playlist/37i9dQZF1DXcBWIGoYBM5M" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Get Spotify Track Details

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves details for a specific Spotify track using its ID. Requires an Authorization Bearer token.

```bash
# Track
curl -s "http://localhost:8000/api/v1/spotify/track/4uLU6hMCjMI75M1A2tKUQC" \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### Caddyfile Configuration for Audiovault

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/REVERSE_PROXY.md

Set up Caddy to reverse proxy requests to Audiovault. Caddy automatically handles basic proxy rules and WebSocket forwarding.

```caddyfile
audiovault.example.com {
    reverse_proxy 127.0.0.1:2137
}
```

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

### Get dashboard statistics

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves key statistics for the user's dashboard, including download counts, library size, and recent activity.

```APIDOC
## GET /api/v1/dashboard/stats

### Description
Fetches statistics for the dashboard, such as total downloads, tracks in the library, pending queue status, free storage, recent activity, and active downloads.

### Method
GET

### Endpoint
/api/v1/dashboard/stats

### Response
#### Success Response (200)
Returns a JSON object containing dashboard statistics, including `total_downloads`, `tracks_in_library`, `pending_queue`, `storage_free`, `recent_activity` array, and `active_download` object.
```

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

### Run Specific Pre-Commit Hook

Source: https://github.com/bl4nk44/audiovault/blob/main/docs/PRE_COMMIT.md

Execute a specific pre-commit hook, such as 'ruff', 'semgrep', or 'eslint-frontend', on all files.

```bash
pre-commit run ruff --all-files
```

```bash
pre-commit run semgrep --all-files
```

```bash
pre-commit run eslint-frontend --all-files
```

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

### Troubleshoot Connection Issues

Source: https://github.com/bl4nk44/audiovault/wiki/Getting-Started

If you encounter connection problems, check if the backend container is running, review its logs for errors, or restart all containers.

```bash
# Check if backend is running
docker compose ps

# Check backend logs
docker compose logs backend | tail -20

# Restart all containers
docker compose restart
```

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

### Get personalized recommendations

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves a list of suggested tracks based on the user's Last.fm listening history. Supports refreshing the recommendations.

```APIDOC
## GET /api/v1/lastfm/recommendations

### Description
Get personalized music recommendations based on Last.fm history.

### Method
GET

### Endpoint
/api/v1/lastfm/recommendations

### Query Parameters
- **force_refresh** (boolean) - Optional - If true, forces a refresh of the recommendations.
- **source** (string) - Optional - Specifies the source for recommendations (e.g., 'auto').

### Request Example
```bash
curl -s "http://localhost:8000/api/v1/lastfm/recommendations?force_refresh=false&source=auto" \
  -H "Authorization: Bearer $TOKEN" | jq
```

### Response
#### Success Response (200)
Returns a `RecommendationResponse` object containing a list of suggested tracks.
```

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

### Get Dashboard Statistics

Source: https://context7.com/bl4nk44/audiovault/llms.txt

Retrieves key statistics for the dashboard, including library size, download status, and recent activity. Requires authentication.

```bash
curl -s http://localhost:8000/api/v1/dashboard/stats \
  -H "Authorization: Bearer $TOKEN" | jq
```

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

### API & Subsonic Configuration Environment Variables

Source: https://github.com/bl4nk44/audiovault/wiki/Configuration

Enable the Subsonic API and configure legacy authentication for older clients.

```bash
# Enable Subsonic API
ENABLE_SUBSONIC_API=true
SUBSONIC_API_VERSION=1.16.1

# Legacy authentication (for older Subsonic clients)
# NOTE: Even with this enabled, you MUST enable "Legacy Auth" / "Use plaintext password"
in your client app settings (Amperfy, Symfonium, etc.)
SUBSONIC_LEGACY_AUTH=true
```