# Valence documentation

> Documentation for Valence, a self-hosted streaming platform for films, programmes, music, books and audiobooks.

Use these Markdown files when you need install guides, product behaviour, plugin documentation, developer notes or API reference material. A complete single-file version is available at `/llms-full.txt`.

## Getting started

- [Introduction](/start/introduction.md): What Valence is, who it is for, what it can and cannot do, how it is licensed and where to get help.
- [System requirements](/start/system-requirements.md): What a Valence server needs in hardware, software, network ports and storage, and which clients can play from it.
- [Quick start](/start/quick-start.md): The fastest path from an empty machine to playing a film, in five steps, using the published Docker image.
- [Concepts](/start/concepts.md): The vocabulary of Valence: libraries, media kinds, accounts and profiles, roles, jobs, requests, playback modes and generated artefacts.
- [Frequently asked questions](/start/faq.md): Short, honest answers to the questions people ask before and after installing Valence.
- [Set up with an AI assistant](/start/set-up-with-an-ai.md): A prompt to paste into ChatGPT, Claude or any other assistant, which asks about your machine and your media and then writes your compose file and the steps to start it.

## Install

- [Complete compose file](/install/complete-compose-file.md): The whole compose.yaml and a starting .env to copy and paste, for a server with a reverse proxy in front of it. Fill in four settings and start it.
- [Docker Compose](/install/docker-compose.md): A full walkthrough of the compose.yaml that ships with Valence, service by service, with the settings file, secrets, first start and a health check.
- [Reverse proxy](/install/reverse-proxy.md): Why Valence needs a reverse proxy, and working configurations for nginx, Caddy, Traefik and Nginx Proxy Manager, with the settings that must agree with them.
- [Configuration](/install/configuration.md): Every setting an operator can change in Valence, grouped by purpose, with defaults and what each one does.
- [Storage and volumes](/install/storage-and-volumes.md): Where Valence keeps each kind of data, which volumes matter, how read only media works, and what to back up.
- [Hardware transcoding](/install/hardware-transcoding.md): Use an Intel, AMD or NVIDIA GPU for transcoding in Valence, with the compose device mapping, how to check it works and how to choose a backend.
- [Hardware transcoding on a Mac](/install/hardware-transcoding-on-a-mac.md): Run Valence's transcoder natively on a Mac so it can use VideoToolbox, with everything else in Docker as usual, and keep it running with launchd.
- [Hardware transcoding on Windows](/install/hardware-transcoding-on-windows.md): Run Valence's transcoder natively on Windows so it can use Intel QuickSync, AMD AMF, NVIDIA NVENC or, on Windows on Arm, Media Foundation, with everything else in Docker as usual.
- [Importing Radarr, Sonarr and the rest](/install/migrating-arr-setup.md): Carry an existing Radarr, Sonarr, Lidarr, Prowlarr and Overseerr or Jellyseerr setup into Valence's requests service, reading from it and never changing it.
- [Requesting](/install/requesting.md): Set up optional media requesting in Valence with indexers, a download client, a VPN, quality profiles and per library behaviour.
- [Desktop app](/install/desktop-app.md): What the desktop app is, how it finds your server, where to download it for each platform and how to build it yourself.
- [Updating](/install/updating.md): How to upgrade Valence safely, which image tag to follow, how database migrations run at start, and how to move to Postgres 18.
- [Rolling back](/install/rolling-back.md): Go back to an older Valence release by restoring the database snapshot taken before the upgrade, and understand why an older release refuses a newer database.
- [Uninstalling](/install/uninstalling.md): How to stop and remove Valence, what each command deletes, and which volumes and files are safe to remove or must be kept.

## Use Valence

- [A tour of Valence](/use/a-tour-of-valence.md): What you see when you open Valence: the home page, a title's page, search, the player and the account menu, and where each is covered in more detail.
- [First run](/use/first-run.md): Walk through the setup wizard, from the administrator to libraries and importing from another server, then sign in and meet the profile picker.
- [Libraries](/use/libraries.md): Add and manage libraries, name your files so they match, scan, upload, correct wrong matches and control what each person can see.
- [Playing media](/use/playing-media.md): Watch, listen and read in Valence, from direct play and quality choices to subtitles, skip intro, watch parties, the music player and the book reader.
- [Accounts and roles](/use/accounts-and-roles.md): Add people to your server, give them roles, limit what they can see, and manage their sign-ins, profiles, passkeys and API keys.
- [Requests](/use/requests.md): Ask for films, series, music and books that are not in your library yet, and approve, track and troubleshoot those requests as an administrator.
- [Jobs and logs](/use/jobs-and-logs.md): See what Valence is doing in the background, run and schedule jobs, stop or pause work, and search the server log with its levels, context and retention.
- [Settings](/use/settings.md): Every option in the admin Settings panel, what it does and its default, plus the Overview, storage recount, re-encoding and the toasts that confirm each change.
- [Notifications and webhooks](/use/notifications-and-webhooks.md): How Valence tells people and other systems what happened, through the in app bell, browser push and signed webhooks, with events, payloads and redelivery.
- [Sharing](/use/sharing.md): Hand out a link so somebody without an account can watch one title, a whole series or read a book, then limit it by time or people and withdraw it at once.
- [Audiobooks](/use/audiobooks.md): How Valence files audiobooks beside your ebooks, and how to listen, with chapters, speed, the sleep timer and carrying on from another device.
- [The phone app](/use/the-phone-app.md): Valence on an iPhone or an Android phone: finding your server, signing in, the tabs, downloads to watch offline, music, audiobooks and sending playback to another screen.
- [Pre-transcoding](/use/pre-transcoding.md): Make a smaller copy of every film and episode ahead of time, in quiet hours, so modest devices play them as they are and a low-powered server never converts while somebody watches.
- [Plugins](/use/plugins.md): Install plugins from the official catalogue or a file, read what they ask for, fill in their settings, grant their permissions, roll them back, and turn them off or remove them.
- [Using Overseerr or Jellyseerr with Valence](/use/overseerr-and-jellyseerr.md): Keep asking for films and series in Overseerr or Jellyseerr, and have Valence fetch them, by adding Valence there as a Radarr and a Sonarr server.
- [Email](/use/email.md): Let Valence email password reset links and setup links through your own mail server or provider, such as Resend, and what that sends where.
- [Collections](/use/collections.md): Group films or series that belong together, such as a saga, a box set or a director's work, by hand or by rules that keep the collection up to date.
- [Moving from Jellyfin, Emby or Plex](/use/migrating.md): Bring people, libraries, watch history, favourites, ratings, collections, playlists, access and intro markers across from an existing media server, safely and as often as you like.
- [Linked servers](/use/linked-servers.md): Pair your Valence with a friend's, choose what each shares, and watch, read, listen and request across the two.
- [Playback errors](/use/playback-errors.md): What each playback error code in Valence means, and what a server's admin can do about it.

## Develop

- [Architecture](/develop/architecture.md): How the Valence server, media service, requests service, web client, desktop app and shared packages fit together, and how a request travels through them.
- [Local setup](/develop/local-setup.md): Install the toolchain, start Postgres (or MySQL or MariaDB), run the server, web client, media service and desktop app, and know which checks guard every commit.
- [Repository layout](/develop/repository-layout.md): Every top level directory, app and package in the Valence monorepo, the import alias each one uses, and the naming and file layout conventions.
- [Coding standard](/develop/coding-standard.md): The binding rules for Valence code, why each exists, what the linters enforce, and the commit, branch and pull request conventions.
- [Testing](/develop/testing.md): How Valence is tested, from co-located Vitest suites and in-memory services to Rust integration tests, coverage floors, fixtures and the media pipeline.
- [Database and migrations](/develop/database-and-migrations.md): How the Drizzle schemas for Postgres and MySQL, migrations, start-up migration, snapshots, rollback and the job queue work, and how to write a safe migration and a query every database reads.
- [Plugins](/develop/plugins.md): How Valence runs plugins without trusting them, the sandbox, permissions, the network rules and how signing decides what may be installed.
- [Realtime](/develop/realtime.md): The single WebSocket for viewer and admin feeds, with message shapes, authentication, topic permissions, reconnection and how a client subscribes.
- [Releasing](/develop/releasing.md): How Valence releases are cut with release-please, how versions and changelogs come from commits, how images are tagged, and how the Discord announcement works.
- [Contributing](/develop/contributing.md): How to contribute to Valence, from finding work and branching to commit format, the pull request checklist, review, licensing and security reports.
- [UI library](/develop/ui-library.md): ValenceUI, the shared component library, covering design tokens, theming and dark mode, how components are built, the ownership rule and adding one.
- [Server compatibility](/develop/server-compatibility.md): How a newer phone, television or desktop app behaves on an older Valence server, and what to do when a change needs the server to do something new.

## Plugins

- [Getting started](/plugins/getting-started.md): Write, build and install your first Valence plugin from the template repository, in about ten minutes.
- [The manifest](/plugins/manifest.md): Every field of manifest.json, what it may hold and the checks Valence makes across fields before a plugin is accepted.
- [Permissions](/plugins/permissions.md): Every permission a plugin can ask for, its exact fields, the host API methods it opens and what an administrator is shown.
- [Host API](/plugins/host-api.md): definePlugin, the handlers a plugin can give, and every method on the valence object with its arguments, results and the permission it needs.
- [Building blocks](/plugins/building-blocks.md): Every block a plugin page or panel can hold, every field on each, how actions and fields travel back, and the limits a surface must keep to.
- [Themes](/plugins/themes.md): Make a Valence theme, the ten colours of a scheme, the corners, and the readability test every theme has to pass.
- [Accounts and OAuth](/plugins/accounts-and-oauth.md): Let people connect their account on another service to your plugin, with Valence running the OAuth flow and keeping the tokens.
- [Schedules and events](/plugins/schedules-and-events.md): Run work on a schedule, or when something happens in Valence, and which profiles that work may act for.
- [Webhooks](/plugins/webhooks.md): Let an outside service tell your plugin about something the moment it happens, at a private address of its own.
- [Download clients and sources](/plugins/download-clients-and-sources.md): Let a remote file service download releases for Valence's requests, or play films straight from it without downloading them first.
- [Packaging](/plugins/packaging.md): The .vplugin package format, its limits, and the valence-plugin command line tool that packs, signs and lists plugins.
- [Signing and the catalogue](/plugins/publishing.md): How the official catalogue is published and signed, how Valence checks it, and how to get a plugin into it.
- [Upgrades and rollback](/plugins/upgrades-and-rollback.md): Change the shape of what your plugin keeps between versions, and what happens when an upgrade goes wrong.
- [Example: anime tracking](/plugins/example-anime-tracking.md): A walk through the official AniList and MyAnimeList plugin, which imports your list and keeps what you have watched in step.
- [Example: playlist import](/plugins/example-playlist-import.md): A walk through the official playlist import plugin, which brings Spotify and Apple Music playlists into Valence and can request the albums of the songs you do not have.

## Reference

- [API overview](/reference/api-overview.md): How to call the Valence HTTP API, with authentication, permissions, errors, pagination, streaming, the WebSocket and worked curl examples.
- [Environment variables](/reference/environment-variables.md): Every environment variable Valence reads, by service, with its type, default and effect, from the server and media service to compose and tooling.
- [Command line](/reference/cli.md): Every command line entry point in Valence, from Migrate and Rollback in the image to the media service binary, pnpm scripts, Docker Compose and drizzle-kit.
- [Ports and sockets](/reference/ports.md): Every port and socket Valence uses, which ones are published on the host and which stay internal, with firewall and reverse proxy guidance.
- [Troubleshooting](/reference/troubleshooting.md): Problems, causes and fixes for Valence installs, using the real messages the server and media service print, from startup and sign-in to playback and disk space.
- [Security](/reference/security.md): How Valence handles authentication, sessions, permissions, secrets and sharing, how to harden an install, and how to report a vulnerability.
- [Links and resources](/reference/links.md): A directory of Valence's repository, releases, changelog, community, container images, licence and policies, plus a guide from what you want to do to the right page.