### Install Frontend Dependencies and Run Dev Server

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Install Node.js dependencies and start the frontend development server using npm.

```bash
npm install
npm run dev
```

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

### Download and Start MediaManager with Docker Compose

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Download the docker-compose.yaml and an example config.toml, then start the MediaManager stack. Ensure you edit config.toml to match your environment before starting.

```bash
# Download docker-compose.yaml
wget -O docker-compose.yaml https://github.com/maxdorninger/MediaManager/releases/latest/download/docker-compose.yaml

# Create config directory and download example configuration
mkdir config
wget -O ./config/config.toml https://github.com/maxdorninger/MediaManager/releases/latest/download/config.example.toml

# Edit config.toml to match your environment
# Then start the stack
docker compose up -d
```

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

### Prepare Configuration Directory and Example Config

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/installation/docker.md

Create a 'config' directory and download the example configuration file 'config.example.toml' into it.

```bash
mkdir config
wget -O ./config/config.toml https://github.com/maxdorninger/MediaManager/releases/latest/download/config.example.toml
```

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

### Example Directory Structure for Import

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/importing-existing-media.md

This example shows the required directory structure for MediaManager to import TV shows and movies. Folders starting with a dot are ignored.

```text
/
└── data/
    ├── tv/
    │   ├── Rick and Morty                          # WILL be imported
    │   ├── Stranger Things (2016) {tvdb_12345} [x265]  # WILL be imported
    │   ├── Breaking Bad (2008) [tmdbid-1396]      # WILL be imported
    │   ├── .The Office (2013)                     # WILL NOT
    │   └── my-custom-library/
    │       └── The Simpsons                       # WILL NOT be imported
    └── movie/
        └── Oppenheimer (2023)                    # WILL be imported
```

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

### Install Project Dependencies

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Install all project dependencies using uv.

```bash
uv sync
```

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

### Install Python with uv

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Install a specific Python version using uv.

```bash
uv python install 3.13
```

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

### Start Development Services with Make

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Use the 'make up' command for an easy way to start all development services defined in the Docker Compose file.

```bash
# Recommended: Use make commands for easy development
make up
```

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

### Download and Run MediaManager with Docker

Source: https://github.com/maxdorninger/mediamanager/blob/master/README.md

Use these commands to download the docker-compose file, create a config directory, download an example configuration file, and start MediaManager in detached mode.

```sh
wget -O docker-compose.yaml https://github.com/maxdorninger/MediaManager/releases/latest/download/docker-compose.yaml
mkdir config
wget -O ./config/config.toml https://github.com/maxdorninger/MediaManager/releases/latest/download/config.example.toml
# you probably need to edit the config.toml file in the ./config directory, for more help see the documentation
docker compose up -d
```

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

### Example Database Configuration (config.toml)

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/database.md

This TOML snippet shows a complete example of the database section in the MediaManager configuration file. Ensure sensitive information like passwords is kept secure.

```toml
[database]
host = "db"
port = 5432
user = "MediaManager"
password = "your_secure_password"
dbname = "MediaManager"
```

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

### Start Development Services with Docker Compose

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Alternatively, use the 'docker compose up' command directly to start the development environment if 'make' is not available.

```bash
docker compose -f docker-compose.dev.yaml up
```

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

### Start Svelte development server

Source: https://github.com/maxdorninger/mediamanager/blob/master/web/README.md

Run 'npm run dev' to start the development server. Use '-- --open' to automatically open the application in a new browser tab.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

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

### Complete MediaManager Configuration Example (config.toml)

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

A comprehensive example of the config.toml file, illustrating settings for miscellaneous options, database connection, authentication (including OpenID Connect), notifications (SMTP and Gotify), download clients (qBittorrent, Transmission, SABnzbd), indexers (Prowlarr, Jackett), and scoring rules for media selection.

```toml
# config.toml - Complete configuration example

[misc]
frontend_url = "http://localhost:8000"
cors_urls = ["http://localhost:8000"]
image_directory = "/data/images"
tv_directory = "/data/tv"
movie_directory = "/data/movies"
torrent_directory = "/data/torrents"
development = false

# Custom Media Libraries
[[misc.tv_libraries]]
name = "Live Action"
path = "/data/tv/live-action"

[[misc.movie_libraries]]
name = "Documentary"
path = "/data/movies/documentary"

[database]
host = "db"
port = 5432
user = "MediaManager"
password = "MediaManager"
dbname = "MediaManager"

[auth]
email_password_resets = false
token_secret = "CHANGE_ME_GENERATE_RANDOM_STRING"  # Generate with: openssl rand -hex 32
session_lifetime = 86400
admin_emails = ["admin@example.com"]

[auth.openid_connect]
enabled = true
client_id = "mediamanager-client"
client_secret = "your-secret-key-here"
configuration_endpoint = "https://auth.example.com/.well-known/openid-configuration"
name = "Authentik"

[notifications.smtp_config]
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_user = "admin"
smtp_password = "admin"
from_email = "mediamanager@example.com"
use_tls = true

[notifications.gotify]
enabled = true
api_key = "your-gotify-api-key"
url = "https://gotify.example.com"

[torrents.qbittorrent]
enabled = true
host = "http://qbittorrent"
port = 8080
username = "admin"
password = "your_secure_password"

[torrents.transmission]
enabled = false
username = "admin"
password = "your_secure_password"
https_enabled = true
host = "transmission"
port = 9091
path = "/transmission/rpc"

[torrents.sabnzbd]
enabled = false
host = "http://sabnzbd"
port = 8080
api_key = "your_sabnzbd_api_key"
base_path = "/api"

[indexers.prowlarr]
enabled = true
url = "http://prowlarr:9696"
api_key = "your_prowlarr_api_key"
timeout_seconds = 60

[indexers.jackett]
enabled = false
url = "http://jackett:9117"
api_key = "your_jackett_api_key"
indexers = ["1337x", "rarbg"]
timeout_seconds = 60

[[indexers.title_scoring_rules]]
name = "prefer_h265"
keywords = ["h265", "hevc", "x265"]
score_modifier = 100
negate = false

[[indexers.title_scoring_rules]]
name = "avoid_cam"
keywords = ["cam", "camrip", "hdcam", "ts", "screener"]
score_modifier = -10000
negate = false

[[indexers.scoring_rule_sets]]
name = "default"
libraries = ["ALL_TV", "ALL_MOVIES"]
rule_names = ["prefer_h265", "avoid_cam"]

[metadata.tmdb]
tmdb_relay_url = "https://metadata-relay.dorninger.co/tmdb"
primary_languages = [""]
default_language = "en"

[metadata.tvdb]
tvdb_relay_url = "https://metadata-relay.dorninger.co/tvdb"

```

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

### Example Metadata Configuration

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/advanced-features/metadata-provider-configuration.md

This TOML snippet shows a complete example of the metadata section in the `config.toml` file, including settings for both TMDB and TVDB.

```toml
[metadata]
    # TMDB configuration
    [metadata.tmdb]
    tmdb_relay_url = "https://metadata-relay.dorninger.co/tmdb"

    # TVDB configuration
    [metadata.tvdb]
    tvdb_relay_url = "https://metadata-relay.dorninger.co/tvdb"

```

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

### Install Node.js with NVM

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Install and use a specific Node.js version using nvm-windows.

```powershell
nvm install 24.1.0
nvm use 24.1.0
```

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

### Prepare Configuration Files

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

On first run, create the configuration directory and copy example configuration files for backend and frontend.

```bash
mkdir -p res/config # Only needed on first run
cp config.dev.toml res/config/config.toml
cp web/.env.example web/.env
```

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

### Example MediaManager Notifications Configuration

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/notifications.md

This TOML snippet shows a complete example of the notifications section in config.toml, demonstrating how to configure SMTP, email, Gotify, Ntfy, and Pushover settings. Multiple notification methods can be enabled simultaneously.

```toml
[notifications]
    # SMTP settings for email notifications and password resets
    [notifications.smtp_config]
    smtp_host = "smtp.gmail.com"
    smtp_port = 587
    smtp_user = "your-email@gmail.com"
    smtp_password = "your-app-password"
    from_email = "mediamanager@example.com"
    use_tls = true

    # Email notification settings
    [notifications.email_notifications]
    enabled = true
    emails = ["admin@example.com", "notifications@example.com"]

    # Gotify notification settings
    [notifications.gotify]
    enabled = true
    api_key = "your_gotify_api_key"
    url = "https://gotify.example.com"

    # Ntfy notification settings
    [notifications.ntfy]
    enabled = false
    url = "https://ntfy.sh/your-private-topic"

    # Pushover notification settings
    [notifications.pushover]
    enabled = false
    api_key = "your_pushover_api_key"
    user = "your_pushover_user_key"

```

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

### Create Frontend Environment File

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Copy the example environment file to create a new .env file for frontend configuration.

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

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

### MediaManager Authentication Configuration Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/authentication.md

This TOML snippet shows a complete example of the authentication section in MediaManager's config.toml file, including both general settings and OpenID Connect configuration.

```toml
[auth]
token_secret = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
session_lifetime = 604800  # 1 week
admin_emails = ["admin@example.com", "manager@example.com"]
email_password_resets = true

[auth.openid_connect]
enabled = true
client_id = "mediamanager-client"
client_secret = "your-secret-key-here"
configuration_endpoint = "https://auth.example.com/.well-known/openid-configuration"
name = "Authentik"

```

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

### TOML Configuration Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/README.md

Example of setting the token secret for authentication in the TOML configuration file. This is a standard way to configure settings directly.

```toml
[auth]
token_secret = "your_super_secret_key_here"
```

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

### Verify uv Installation

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Check if the uv package manager is installed and accessible.

```bash
uv --version
```

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

### Run Backend Development Server

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Start the FastAPI backend server in development mode with automatic reloading.

```bash
uv run fastapi run media_manager/main.py --reload --port 8000
```

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

### Example MediaManager config.toml

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/indexers.md

This TOML configuration demonstrates how to set up both Prowlarr and Jackett indexers. Ensure your API keys and URLs are correct for each service.

```toml
[indexers]
[indexers.prowlarr]
enabled = true
url = "http://prowlarr:9696"
api_key = "your_prowlarr_api_key"
timeout_seconds = 60

[indexers.jackett]
enabled = false
url = "http://jackett:9117"
api_key = "your_jackett_api_key"
indexers = ["1337x", "rarbg"]
timeout_seconds = 60
```

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

### Environment Variable Configuration Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/README.md

Demonstrates how to set the token secret for authentication using an environment variable. This method is preferred for sensitive information.

```none
MEDIAMANAGER_AUTH__TOKEN_SECRET = "your_super_secret_key_here"
```

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

### Configure Download Clients in TOML

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/download-clients.md

Example TOML configuration for integrating qBittorrent, Transmission, and SABnzbd with MediaManager. Ensure only one BitTorrent and one Usenet client are enabled.

```toml
[torrents]
    # qBittorrent configuration
    [torrents.qbittorrent]
    enabled = true
    host = "http://qbittorrent"
    port = 8080
    username = "admin"
    password = "your_secure_password"

    # Transmission configuration
    [torrents.transmission]
    enabled = false
    username = "admin"
    password = "your_secure_password"
    https_enabled = true
    host = "transmission"
    port = 9091
    path = "/transmission/rpc"

    # SABnzbd configuration
    [torrents.sabnzbd]
    enabled = false
    host = "http://sabnzbd"
    port = 8080
    api_key = "your_sabnzbd_api_key"

```

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

### General Backend Settings Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/backend.md

This TOML snippet shows the general settings for the MediaManager backend. Ensure 'frontend_url' matches your deployment. 'cors_urls' should list valid origins, and 'development' can be set to true for debugging.

```toml
[misc]

# REQUIRED: Change this to match your actual frontend domain.
frontend_url = "http://mediamanager.dev"

cors_urls = ["http://localhost:8000"]

# Optional: Development mode (set to true for debugging)
development = false

```

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

### Docker Compose for Download Clients

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/download-clients.md

Example Docker Compose configuration to set up qBittorrent and SABnzbd services accessible by the MediaManager backend. Ensure download directories are accessible.

```yaml
services:
  # MediaManager backend
  backend:
    image: ghcr.io/maxdorninger/mediamanager/backend:latest
    # ... other configuration ...

  # qBittorrent service
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    ports:
      - "8080:8080"
    environment:
      - WEBUI_PORT=8080
    volumes:
      - ./data/torrents:/downloads
    # ... other configuration ...

  # SABnzbd service
  sabnzbd:
    image: lscr.io/linuxserver/sabnzbd:latest
    ports:
      - "8081:8080"
    volumes:
      - ./data/usenet:/downloads
    # ... other configuration ...

```

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

### Directory Structure After Import

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/importing-existing-media.md

This example illustrates how the directory structure changes after MediaManager imports media. Imported folders are prefixed with a dot.

```text
/
└── data/
    ├── tv/
    │   ├── .Rick and Morty                          # RENAMED
    │   ├── Rick and Morty (2013) [tmdbid-60625]     # IMPORTED
    │   ├── .Stranger Things (2016) {tvdb_12345}    # RENAMED
    │   ├── Stranger Things (2016) [tmdbid-66732]    # IMPORTED
    │   ├── .The Office (2013)                       # IGNORED
    │   ├── .Breaking Bad (2008) [tmdbid-1396]       # RENAMED
    │   ├── Breaking Bad (2008) [tmdbid-1396]        # IMPORTED
    │   └── my-custom-library/
    │       └── The Simpsons                         # IGNORED
    └── movie/
        ├── .Oppenheimer (2023)                      # RENAMED
        └── Oppenheimer (2023) [tmdbid-872585]       # IMPORTED
```

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

### Movies - Get Available Libraries

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

List all configured movie libraries from the configuration file.

```APIDOC
## GET /api/v1/movies/libraries

### Description
List all configured movie libraries from the configuration file.

### Method
GET

### Endpoint
/api/v1/movies/libraries

### Response
#### Success Response (200)
- **name** (string) - The name of the library.
- **path** (string) - The file system path of the library.

#### Response Example
```json
[
  {
    "name": "Documentary",
    "path": "/data/movies/documentary"
  },
  {
    "name": "Foreign Films",
    "path": "/data/movies/foreign"
  }
]
```
```

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

### Get All Users

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve a list of all registered users. This endpoint is restricted to superusers only and requires authentication.

```bash
# Get all users
curl -X GET "http://localhost:8000/api/v1/users/all" \
  -H "Authorization: Bearer $TOKEN"
```

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

### GET /api/v1/tv/shows/libraries

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all configured TV libraries available in the MediaManager configuration.

```APIDOC
## GET /api/v1/tv/shows/libraries

### Description
Lists all configured TV libraries from the configuration file.

### Method
GET

### Endpoint
`/api/v1/tv/shows/libraries`

### Response
#### Success Response
An array of library objects, each containing `name` and `path`.

### Response Example
```json
[
  {
    "name": "Live Action",
    "path": "/data/tv/live-action"
  },
  {
    "name": "Animation",
    "path": "/data/tv/animation"
  }
]
```

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/tv/shows/libraries" \
  -H "Authorization: Bearer $TOKEN"
```
```

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

### Get Recommended TV Shows

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Fetches a list of recommended or popular TV shows. Requires an authorization token.

```bash
curl -X GET "http://localhost:8000/api/v1/tv/recommended" \
  -H "Authorization: Bearer $TOKEN"
```

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

### OpenID Connect Callback URI

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/authentication.md

This is an example of the redirect URI required by your OpenID server when integrating with MediaManager. Ensure this is set correctly in your provider's configuration.

```none
{MEDIAMANAGER_URL}/api/v1/auth/oauth/callback

```

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

### Get All TV Shows in Library

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all TV shows currently stored in the MediaManager library. Requires an authorization token.

```bash
# Get all shows in library
curl -X GET "http://localhost:8000/api/v1/tv/shows" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Example Timeout Log

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/indexers.md

This log snippet illustrates a typical read timeout error when MediaManager attempts to connect to an indexer. Adjust the `timeout_seconds` setting if you encounter frequent timeouts.

```none
DEBUG - media_manager.indexer.utils -
 follow_redirects_to_final_torrent_url():
  An error occurred during the request for <some-url>:
   HTTPConnectionPool(host='<some-host>', port=<some-port>):
    Read timed out. (read timeout=10)
```

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

### OpenID Connect Client Secret TOML Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/README.md

Shows how to configure the OpenID Connect client secret within the TOML file. This is part of the authentication settings.

```toml
[auth]
... 
[auth.openid_connect]
client_secret = "your_client_secret_from_provider"
```

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

### Start MediaManager with Docker Compose

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/installation/docker.md

This command brings up the MediaManager stack in detached mode. MediaManager will create default configuration and admin user on first run if they don't exist.

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

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

### OpenID Connect Client Secret Environment Variable Example

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/README.md

Illustrates setting the OpenID Connect client secret via an environment variable. This follows the nested structure convention for environment variables.

```none
MEDIAMANAGER_AUTH__OPENID_CONNECT__CLIENT_SECRET = "your_client_secret_from_provider"
```

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

### Get Available Movie Libraries

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all configured movie libraries from the configuration file. This helps in organizing and assigning movies to specific paths.

```bash
# Get available movie libraries
curl -X GET "http://localhost:8000/api/v1/movies/libraries" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Get Available TV Libraries

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all configured TV libraries from the application's configuration file. This endpoint does not require any specific show ID.

```bash
curl -X GET "http://localhost:8000/api/v1/tv/shows/libraries" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Get Recommended Movies

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve a list of popular or recommended movies from the metadata provider. Authentication via a Bearer token is required.

```bash
# Get recommended/popular movies
curl -X GET "http://localhost:8000/api/v1/movies/recommended" \
  -H "Authorization: Bearer $TOKEN"
```

```json
# Response:
# [
#   {
#     "id": 872585,
#     "name": "Oppenheimer",
#     "overview": "The story of American scientist J. Robert Oppenheimer...",
#     "year": 2023,
#     "poster_path": "/8Gxv8gSFCU0XGDykEGv7zR1n2ua.jpg"
#   }
# ]
```

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

### Get Movie Files

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Fetches all files associated with a specific movie. This includes details like file path, quality, and import status.

```bash
# Get movie files
curl -X GET "http://localhost:8000/api/v1/movies/550e8400-e29b-41d4-a716-446655440000/files" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Get Recommended TV Shows

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of popular or recommended TV shows from the metadata provider. This is useful for discovering new content.

```bash
# Get recommended TV shows
curl -X GET "http://localhost:8000/api/v1/tv/popular" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Complete MediaManager Nix Flake Configuration

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/installation/flakes.md

A minimal, complete Nix flake configuration for MediaManager, including service enablement, PostgreSQL setup, port, data directory, and frontend URL settings. It also configures systemd tmpfiles for media directories.

```nix
{ description = "An example NixOS configuration";

  inputs = {
    nixpkgs = { url = "github:nixos/nixpkgs/nixos-unstable"; };
    mediamanager-nix = {
      url = "github:strangeglyph/mediamanager-nix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = inputs@{ ... };
}
```

```nix
{ config = {
    services.media-manager = {
      enable = true;
      postgres.enable = true;
      port = 12345;
      dataDir = "/tmp";
      settings = {
        misc.frontend_url = "http://[::1]:12345";
      };
    };

    systemd.tmpfiles.settings."10-mediamanager" = {
      "/tmp/movies".d = { user = config.services.media-manager.user; };
      "/tmp/shows".d = { user = config.services.media-manager.user; };
      "/tmp/images".d = { user = config.services.media-manager.user; };
      "/tmp/torrents".d = { user = config.services.media-manager.user; };
    };
  };
};
}
```

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

### Get All Movies in Library

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve a list of all movies currently stored in the user's library. Authentication via a Bearer token is required.

```bash
# Get all movies in library
curl -X GET "http://localhost:8000/api/v1/movies" \
  -H "Authorization: Bearer $TOKEN"
```

```json
# Response:
# [
#   {
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "name": "Inception",
#     "overview": "A thief who steals corporate secrets...",
#     "year": 2010,
#     "external_id": 27205,
#     "metadata_provider": "tmdb",
#     "library": "Default",
#     "original_language": "en",
#     "imdb_id": "tt1375666"
#   }
# ]
```

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

### Get Importable TV Shows

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of TV shows that exist on disk but are not yet present in the MediaManager database. This helps in identifying media for import.

```bash
curl -X GET "http://localhost:8000/api/v1/tv/importable" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Get Specific TV Show Details

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Fetches detailed information for a specific TV show, including seasons, episodes, and download status, using its library ID.

```bash
# Get show by ID
curl -X GET "http://localhost:8000/api/v1/tv/shows/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Movies - Get Movie Files

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Get all files associated with a specific movie.

```APIDOC
## GET /api/v1/movies/{movie_id}/files

### Description
Get all files associated with a specific movie.

### Method
GET

### Endpoint
/api/v1/movies/{movie_id}/files

### Response
#### Success Response (200)
- **movie_id** (string) - The ID of the movie.
- **file_path_suffix** (string) - The suffix of the file path.
- **quality** (string) - The quality of the media file.
- **torrent_id** (string) - The ID of the torrent associated with the file.
- **imported** (boolean) - Indicates if the file has been imported.

#### Response Example
```json
[
  {
    "movie_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_path_suffix": "",
    "quality": "fullhd",
    "torrent_id": "880e8400-e29b-41d4-a716-446655440003",
    "imported": true
  }
]
```
```

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

### Movies - Get Recommended Movies

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Get a list of popular/recommended movies from the metadata provider.

```APIDOC
## Movies - Get Recommended Movies

### Description
Retrieve a list of popular or recommended movies from the configured metadata provider. Requires authentication.

### Method
GET

### Endpoint
/api/v1/movies/recommended

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/movies/recommended" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the movie from the metadata provider.
- **name** (string) - The title of the movie.
- **overview** (string) - A brief synopsis of the movie.
- **year** (integer) - The release year of the movie.
- **poster_path** (string) - The path to the movie's poster image on the metadata provider.

#### Response Example
```json
[
  {
    "id": 872585,
    "name": "Oppenheimer",
    "overview": "The story of American scientist J. Robert Oppenheimer...",
    "year": 2023,
    "poster_path": "/8Gxv8gSFCU0XGDykEGv7zR1n2ua.jpg"
  }
]
```
```

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

### Movies - Get Movie Details

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Get detailed information about a specific movie including download status and associated torrents.

```APIDOC
## Movies - Get Movie Details

### Description
Retrieve detailed information for a specific movie in the library, identified by its internal ID. This includes metadata, download status, and associated torrents. Requires authentication.

### Method
GET

### Endpoint
/api/v1/movies/{movie_id}

### Parameters
#### Path Parameters
- **movie_id** (string) - Required - The internal unique identifier of the movie.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/movies/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - The unique internal identifier for the movie in the library.
- **name** (string) - The title of the movie.
- **overview** (string) - A brief synopsis of the movie.
- **year** (integer) - The release year of the movie.
- **external_id** (integer) - The ID of the movie from the metadata provider.
- **metadata_provider** (string) - The name of the metadata provider (e.g., 'tmdb').
- **library** (string) - The name of the library the movie was added to.
- **original_language** (string) - The original language of the movie.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Inception",
  "overview": "A thief who steals corporate secrets...",
  "year": 2010,
  "external_id": 27205,
  "metadata_provider": "tmdb",
  "library": "Default",
  "original_language": "en"
}
```
```

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

### GET /api/v1/notification/unread

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves only unread notifications.

```APIDOC
## GET /api/v1/notification/unread

### Description
Retrieves only unread notifications for display in the UI.

### Method
GET

### Endpoint
/api/v1/notification/unread

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the notification.
- **title** (string) - The title of the notification.
- **message** (string) - The content of the notification.
- **read** (boolean) - Indicates if the notification has been read.
- **created_at** (string) - The timestamp when the notification was created.

#### Response Example
```json
[
  {
    "id": "ee0e8400-e29b-41d4-a716-446655440009",
    "title": "Download Complete",
    "message": "Breaking Bad S01 has finished downloading",
    "read": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
]
```
```

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

### Run Database Migrations

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Apply pending database migrations using alembic with uv.

```bash
uv run alembic upgrade head
```

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

### GET /api/v1/notification

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves all notifications in the system.

```APIDOC
## GET /api/v1/notification

### Description
Retrieves all notifications in the system.

### Method
GET

### Endpoint
/api/v1/notification

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the notification.
- **title** (string) - The title of the notification.
- **message** (string) - The content of the notification.
- **read** (boolean) - Indicates if the notification has been read.
- **created_at** (string) - The timestamp when the notification was created.

#### Response Example
```json
[
  {
    "id": "ee0e8400-e29b-41d4-a716-446655440009",
    "title": "Download Complete",
    "message": "Breaking Bad S01 has finished downloading",
    "read": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
]
```
```

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

### GET /api/v1/notification/{id}

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a specific notification by its ID.

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

### Description
Retrieves a specific notification by its ID.

### Method
GET

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

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

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the notification.
- **title** (string) - The title of the notification.
- **message** (string) - The content of the notification.
- **read** (boolean) - Indicates if the notification has been read.
- **created_at** (string) - The timestamp when the notification was created.

#### Response Example
```json
{
  "id": "ee0e8400-e29b-41d4-a716-446655440009",
  "title": "Download Complete",
  "message": "Breaking Bad S01 has finished downloading",
  "read": false,
  "created_at": "2024-01-15T10:30:00Z"
}
```
```

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

### Movies - Get All Movies

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve all movies currently in the library.

```APIDOC
## Movies - Get All Movies

### Description
Retrieve a list of all movies that have been added to the user's library. Requires authentication.

### Method
GET

### Endpoint
/api/v1/movies

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/movies" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - The unique internal identifier for the movie in the library.
- **name** (string) - The title of the movie.
- **overview** (string) - A brief synopsis of the movie.
- **year** (integer) - The release year of the movie.
- **external_id** (integer) - The ID of the movie from the metadata provider.
- **metadata_provider** (string) - The name of the metadata provider (e.g., 'tmdb').
- **library** (string) - The name of the library the movie was added to.
- **original_language** (string) - The original language of the movie.
- **imdb_id** (string) - The IMDb ID of the movie.

#### Response Example
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Inception",
    "overview": "A thief who steals corporate secrets...",
    "year": 2010,
    "external_id": 27205,
    "metadata_provider": "tmdb",
    "library": "Default",
    "original_language": "en",
    "imdb_id": "tt1375666"
  }
]
```
```

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

### GET /api/v1/torrent/{id}

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves details of a specific torrent by its ID.

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

### Description
Retrieves details of a specific torrent by its ID.

### Method
GET

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

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

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/torrent/dd0e8400-e29b-41d4-a716-446655440008" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the torrent.
- **status** (string) - The current status of the torrent (e.g., downloading, finished, error).
- **title** (string) - The title of the torrent.
- **quality** (string) - The quality of the media.
- **imported** (boolean) - Indicates if the torrent has been imported.
- **hash** (string) - The hash of the torrent.
- **usenet** (boolean) - Indicates if the torrent is from Usenet.

#### Response Example
```json
{
  "id": "dd0e8400-e29b-41d4-a716-446655440008",
  "status": "downloading",
  "title": "Breaking.Bad.S01.1080p.BluRay.x265.HEVC",
  "quality": "fullhd",
  "imported": false,
  "hash": "efgh5678...",
  "usenet": false
}
```
```

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

### GET /api/v1/users/all

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all registered users. This endpoint is restricted to superusers.

```APIDOC
## GET /api/v1/users/all

### Description
Retrieves a list of all registered users. This endpoint is restricted to superusers.

### Method
GET

### Endpoint
/api/v1/users/all

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **email** (string) - The email address of the user.
- **is_active** (boolean) - Indicates if the user account is active.
- **is_superuser** (boolean) - Indicates if the user has superuser privileges.
- **is_verified** (boolean) - Indicates if the user's email has been verified.

#### Response Example
```json
[
  {
    "id": "ff0e8400-e29b-41d4-a716-446655440010",
    "email": "admin@example.com",
    "is_active": true,
    "is_superuser": true,
    "is_verified": true
  },
  {
    "id": "gg0e8400-e29b-41d4-a716-446655440011",
    "email": "user@example.com",
    "is_active": true,
    "is_superuser": false,
    "is_verified": true
  }
]
```
```

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

### Create a new Svelte project

Source: https://github.com/maxdorninger/mediamanager/blob/master/web/README.md

Use 'npx sv create' to initialize a new Svelte project. Specify a directory name to create the project in a subfolder.

```bash
npx sv create

# create a new project in my-app
npx sv create my-app
```

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

### Get All Notifications

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve a list of all notifications in the system. This endpoint requires authentication.

```bash
# Get all notifications
curl -X GET "http://localhost:8000/api/v1/notification" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Follow All Service Logs

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Follow logs for all services in real-time.

```bash
make logs ARGS="--follow"
```

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

### Get Recommended/Popular Shows

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of recommended or popular TV shows.

```APIDOC
## GET /api/v1/tv/recommended

### Description
Retrieves a list of recommended or popular TV shows.

### Method
GET

### Endpoint
/api/v1/tv/recommended

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/tv/recommended" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the show.
- **name** (string) - The title of the TV show.
- **overview** (string) - A brief synopsis of the show.
- **year** (integer) - The release year of the show.
- **poster_path** (string) - The path to the show's poster image.

#### Response Example
```json
[
  {
    "id": 60625,
    "name": "Rick and Morty",
    "overview": "Rick is a mentally-unbalanced but scientifically gifted old man...",
    "year": 2013,
    "poster_path": "/cvhNj9eoRBe5SxjCbQTkh05wJwM.jpg"
  }
]
```
```

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

### Import Community MediaManager Nix Flake

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/installation/flakes.md

Import the community-provided mediamanager-nix flake into your system's flake configuration. Ensure nixpkgs is followed to maintain consistency.

```nix
{ description = "An example NixOS configuration";

  inputs = {
    nixpkgs = { url = "github:nixos/nixpkgs/nixos-unstable"; };
    
    mediamanager-nix = {
      url = "github:strangeglyph/mediamanager-nix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = inputs@{ ... };
}
```

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

### Configure Custom TV Show Libraries

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/custom-libraries.md

Configure custom TV show libraries by adding `[[misc.tv_libraries]]` sections in `config.toml`. Specify a name and the absolute path for each TV show library.

```toml
[misc]

# ... other misc settings

[[misc.tv_libraries]]
name = "Live Action"
path = "/data/tv/live-action"

[[misc.tv_libraries]]
name = "Animation"
path = "/data/tv/animation"
```

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

### Enable MediaManager Service

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/installation/flakes.md

Enable the MediaManager systemd service by setting `services.media-manager.enable` to true in your NixOS configuration.

```nix
{ config = {
    services.media-manager = {
      enable = true;
    };
  };
}
```

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

### Configure Custom Movie Libraries

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/configuration/custom-libraries.md

Add custom movie libraries by defining `[[misc.movie_libraries]]` sections in `config.toml`. Each library requires a unique name and the absolute path to the media folder.

```toml
[misc]

# ... other misc settings

[[misc.movie_libraries]]
name = "Action"
path = "/data/movies/action"

[[misc.movie_libraries]]
name = "Comedy"
path = "/data/movies/comedy"
```

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

### API Health Check

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Verify the MediaManager API is running and get the current version.

```APIDOC
## API Health Check

### Description
Verify the MediaManager API is running and get the current version.

### Method
GET

### Endpoint
/api/v1/health

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/health"
```

### Response
#### Success Response (200)
- **message** (string) - A greeting message.
- **version** (string) - The current API version.

#### Response Example
```json
{
  "message": "Hello World!",
  "version": "1.12.0"
}
```
```

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

### Build Docker Image with Base Path

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/advanced-features/url-prefix.md

Build the Docker image for MediaManager with a custom base path. This argument is required for SvelteKit to know the base URL at build time.

```none
docker build \
  --build-arg BASE_PATH=/media \
  --build-arg VERSION=my-custom-version \
  -t MediaManager:my-custom-version \
  -f Dockerfile .
```

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

### Follow Backend Logs

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Follow backend logs in real-time, specifying the service.

```bash
make logs ARGS="--follow mediamanager"
```

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

### Get Notification by ID

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Fetch a specific notification using its unique identifier. Authentication is required.

```bash
# Get notification by ID
curl -X GET "http://localhost:8000/api/v1/notification/ee0e8400-e29b-41d4-a716-446655440009" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Get Torrent by ID

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieve details of a specific torrent using its ID. Requires authentication.

```bash
curl -X GET "http://localhost:8000/api/v1/torrent/dd0e8400-e29b-41d4-a716-446655440008" \
  -H "Authorization: Bearer $TOKEN"
```

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

### GET /api/v1/torrent

Source: https://context7.com/maxdorninger/mediamanager/llms.txt

Retrieves a list of all torrents currently managed by the system, regardless of their association with media.

```APIDOC
## GET /api/v1/torrent

### Description
Retrieve all torrents in the system regardless of associated media.

### Method
GET

### Endpoint
`/api/v1/torrent`

### Response
#### Success Response
An array of torrent objects, each containing details like `id`, `status`, `title`, `quality`, `imported`, `hash`, and `usenet`.

### Response Example
```json
[
  {
    "id": "dd0e8400-e29b-41d4-a716-446655440008",
    "status": "downloading",
    "title": "Breaking.Bad.S01.1080p.BluRay.x265.HEVC",
    "quality": "fullhd",
    "imported": false,
    "hash": "efgh5678...",
    "usenet": false
  },
  {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "finished",
    "title": "Inception.2010.2160p.UHD.BluRay.x265.HEVC",
    "quality": "uhd",
    "imported": true,
    "hash": "abcd1234...",
    "usenet": false
  }
]
```

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/torrent" \
  -H "Authorization: Bearer $TOKEN"
```
```

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

### Create Virtual Environment with uv

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Create a new virtual environment using uv, specifying the Python version.

```bash
uv venv --python 3.13
```

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

### Create New Database Migration

Source: https://github.com/maxdorninger/mediamanager/blob/master/docs/contributing-to-mediamanager/developer-guide.md

Create a new database migration file with autogenerated changes.

```bash
make app
uv run alembic revision --autogenerate -m "description"
```