CoffeeKnyteandGitHub
021e54a03c
* fix(scanner): stop classifying "other" content folders as extras Regression from #322 (trailers and extras for movies and series), which introduced the extrasDirKinds map. The extras directory classifier mapped the generic labels "other" and "others" to ExtraKindOther. These are not part of the Jellyfin/Plex extras folder convention the map claims to mirror, and they collide with real content-scope folder names. A library organized as "movies/other/<Title (year) {ids}>/<file>" tripped the depth-2 ancestor lookup in classifyExtraPath: every title two levels under the scope folder "other" was classified as an "other"-kind extra. Such files are partitioned out of primary root/group inference and matching, then deferred in processExtraFiles because their parent cannot resolve (they are the primary titles, not children of one). The result on one deployment was ~10k movies under a folder named "other" funneled through the slow extras path every scan (parent-unresolved deferrals at ~9.5/s), stalling the scan and freezing that scope for new/changed primary content. Remove "other"/"others" from extrasDirKinds. The ExtraKindOther kind stays reachable through genuine convention labels (extra/extras/interviews/ scenes/shorts). Add regression coverage asserting titles under a scope folder named other/others stay primary. * perf(scanner): rewrite identity-only changes without re-probing A pure identity/grouping change on an already-probed file — a root_assignment_changed or group_assignment_changed reason with nothing else — used to fall into the full update branch, which unconditionally ran ffprobe (probeFile) and then upserted every column, including probe columns, from the freshly built row. When a group-key or root scheme changes across the library (see #319), this reprobed nearly every file on the next scan: an incremental scan that normally takes ~1h ran 7h+ as a full-library ffprobe storm, even though the media bytes were untouched. Add a metadata-only update path in processFile: when identityOnlyUpdateReasons reports every reason is a root/group reassignment, rewrite just the derived identity columns via the new FileRepository.UpdateIdentity and skip ffprobe, OSHash, and marker fetch entirely. UpdateIdentity issues a targeted UPDATE of the root/group/identity and edition/presentation columns only, mirroring Upsert's column handling, and leaves probe data, file bytes/mtime/hash, subtitles, chapters, markers, and content/episode/extra linkage intact. The stored group key converges to the recomputed value on the next scan, so the file takes the unchanged fast-path thereafter — without a probe storm. The shared identity-column population is extracted into populateScanIdentity so the full path and the metadata-only path stay in lockstep. Verification: unit test for the identityOnlyUpdateReasons classifier; a DB-backed test (skipped without SILO_TEST_DATABASE_URL) asserting UpdateIdentity rewrites grouping while preserving probe/linkage columns; the UPDATE statement was also exercised against the live schema inside a rolled-back transaction. * fix(scanner): harden identity fast path and extras scope classification Review follow-ups for the two scan-regression fixes on this branch, addressing both Codex review comments on PR #341 plus adversarial-review findings. Identity fast path (processFile/UpdateIdentity): - Gate the metadata-only path on existing.ExtraID == "": a row still linked as an extra reaching processFile is being reclassified as primary, and only the full upsert clears extra linkage; UpdateIdentity would have frozen it out of matching forever (match backlog filters extra_id IS NULL). - Gate on existing.FileHash != "": the full path backfills the OSHash and fetches hash-keyed S3 intro/credits markers, which no later scan reason would repair; hash-less legacy rows now take the full path once instead of silently losing that repair channel. file_hash is added to the scan-state row shape to support the gate. - Clear match_suppressed_at like every other scan write, so files with fresh identity re-enter the match backlog (suppression is documented as lasting "until retried or seen by a new scan"). - Write media_folder_id, mirroring Upsert's ON CONFLICT reassignment. - Return ErrFileNotFound when the row vanished mid-scan (concurrent delete) and fall through to the full upsert path instead of surfacing a per-file scan error. - Return only the row id instead of RETURNING all ~75 columns: the fast path fires once per file during library-wide grouping migrations, and dragging the track/chapter JSONB payloads along for a million rows dominated the cost of the path built to be cheap. - Extract identityColumnDefaults shared by Upsert and UpdateIdentity so the defaulting rules cannot drift, and drop the no-op editionConfidence indirection copied between them. - Use populateScanIdentity in the new-file insert path too; it still carried a verbatim copy of the extracted block (with a provably dead existingByPath lookup). Extras classification: - Restore "other" to extrasDirKinds: it is part of both the documented Jellyfin and Plex extras-folder conventions (the removed-label fix overshot and broke "movies/<Title>/Other/<file>" libraries, ingesting their extras as bogus primary titles). "others" stays removed - it is in neither convention. - Replace label removal with the structural guard the PR had deferred: classifyExtraPath now rejects a supplemental-named directory sitting at library-scope depth (the dir, any supplemental ancestor, or the first non-supplemental ancestor is a configured library root). This fixes the original "movies/other/<Title>" defer-storm generically, covering every convention label (shorts, scenes, extras, ...) used as a content-scope folder. - Scope extras parent binding by folder.Paths instead of the walk roots, so a subtree scan targeting a single movie folder still binds that movie's own extras instead of deferring them. Tests: eligibility-gate unit tests, scope-guard classifier cases (convention Other/ inside a title binds; scope-level other/shorts stay primary), and the DB-backed UpdateIdentity test now also covers folder moves, suppression clearing, and ErrFileNotFound. Full scanner suite ran green against a migrated scratch PostgreSQL 17 container. * refactor(scanner): simplify extras scope guard to title-folder rule Replace the ancestor-walking supplementalDirAtScopeDepth loop with the plain rule it was approximating: a convention-named directory counts as an extras dir only when it sits inside a title folder — it must not be a configured library root or directly under one. Same outcome for the layouts that matter (movies/other/<Title> stays primary, <Title>/Other classifies), less machinery. * test(scanner): assert all rewritten identity columns in UpdateIdentity test * fix(scanner): make extras scope classification structure-aware The title-folder rule from 53632022 anchored on library roots, so it missed both directions: chained convention dirs at the root ("movies/extras/behind the scenes/clip.mkv") classified as extras with an unresolvable parent (deferred forever), and category folders nested below the root ("movies/4K/other/<Title>/") still misclassified their titles. Replace the root-distance heuristic with the structural property that actually distinguishes the two cases: a convention-named directory only counts as an extras dir when its owner (first non-supplemental ancestor) is a title folder — a directory that holds media of its own. The new extrasClassifier derives that from the scan's walked path list (no extra I/O): movie folders must hold a file directly beside the extras dir; series folders may hold episodes one level down in season folders (media hiding inside a folder's own extras dirs doesn't count). Library roots never qualify. Watch-event scans, which have no walked list, probe ownership with bounded os.ReadDir instead. This handles title folders at any depth below the root and keeps scope/category folders primary at any depth, with two known edges: a title folder holding only extras (its media file missing) stays primary until the file appears, and a mixed dir holding both loose media and a category folder degrades to deferral, never wrong linkage. resolveExtraParent's inline supplemental-chain walk is extracted into the shared firstNonSupplementalAncestor.
Silo
Silo is a self-hosted media streaming server for your movies, shows, music, and books. Point it at your media folders and stream to your devices — at home or away — with direct play, remuxing, and hardware-accelerated transcoding handled automatically.
Join the community on Discord. If Silo is useful to you, consider sponsoring the project — see Supporting Silo.
Highlights
- Plays your media, your way — direct play when the device supports it, remux or hardware-accelerated transcode (including NVENC) when it doesn't.
- Web app included — a full-featured web client and admin interface ship with the server.
- Works with apps you already use — optional Jellyfin/Emby-compatible API supports clients such as VidHub, Findroid, and Infuse.
- Household profiles — multiple profiles per account, with per-profile watch state and parental controls.
- Plugin-driven metadata — match and enrich your libraries with providers like TMDB and TVDB, installed as plugins.
- Fast setup — one
docker compose up -dbrings up the whole stack; everything else is configured in the admin UI.
Deploy with Docker (recommended)
The easiest way to run Silo is with Docker Compose. The default stack assumes you do not already have PostgreSQL and Redis available, so it bundles PostgreSQL, Redis, FFmpeg, and the application for a one-command start.
-
Create a
.envfilecp .env.example .env -
Set your media path
Edit
.envand set:MEDIA_ROOT=/path/to/your/mediaMEDIA_ROOTis the one value most users need to change. You can also overrideSILO_DATA_ROOTif you do not want bind mounts under/opt/silo, and change ports if the defaults conflict with something else on the host. -
Start the default integrated stack
docker compose up -dThis starts PostgreSQL, Redis, and the integrated Silo server. The app is available at
http://localhost:8090. Jellyfin-compatible app support is disabled until an administrator enables it in onboarding or admin settings.If you already have PostgreSQL and Redis available, omit those bundled service examples from compose and point Silo at your existing
DATABASE_URLandREDIS_URLinstead.Optional NVIDIA/NVENC
GPU support is kept out of the default compose file so hosts without NVIDIA drivers work unchanged.
Install the NVIDIA Container Toolkit and use a Docker Compose version with GPU reservation support before enabling this override.
Use the optional override file when you want NVENC:
docker compose -f docker-compose.yml -f docker-compose.nvidia.yml up -dIf you want this controlled from
.env, setCOMPOSE_FILE:COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml NVIDIA_GPU_COUNT=1Windows uses
;instead of:between compose files.Then
docker compose up -dwill include the NVIDIA override automatically. -
Configure through the admin UI
Add libraries, users, metadata providers, and playback settings from the web interface.
Bind Mount Layout
The deploy-oriented compose files use host folder mappings rather than Docker-managed volumes.
By default, data is stored under /opt/silo:
/opt/silo/postgres/opt/silo/redis/opt/silo/transcode/opt/silo/catalog-seeds
Media is mounted into the container at /mnt/media from the host path you set in MEDIA_ROOT.
Optional Profiles
The main compose file is integrated-first. These profiles exist for operators testing distributed mode or mirroring a split deployment shape. Most single-host installs should stay on the default integrated service, because it already includes proxying and transcoding.
| Profile | Command | Description |
|---|---|---|
| default | docker compose up -d |
Integrated server plus bundled PostgreSQL and Redis |
proxy |
docker compose --profile proxy up -d |
Start a standalone proxy service for distributed-mode testing |
transcode |
docker compose --profile transcode up -d |
Start a standalone transcode service for distributed-mode testing |
You can enable both optional examples together:
docker compose --profile proxy --profile transcode up -d
If you are splitting workers across multiple hosts, use the separate remote worker example instead of trying to stretch the main compose file across machines.
Advanced Remote Node Example
For a dedicated remote transcode worker, use docker-compose.remote-transcode.yml. That file is intended for a separate worker host that connects back to an existing Silo deployment using shared PostgreSQL and Redis.
Deployment Notes
The default compose stack intentionally bundles PostgreSQL and Redis for ease of setup and assumes a fresh install without those services already available. If you already operate PostgreSQL and Redis, omit those examples from compose and point Silo at your existing infrastructure instead. For serious installs, PostgreSQL is better on a separate VM or a managed service so upgrades, tuning, and backups are isolated from the app host. Redis can stay local for many installs, but externalizing it is also reasonable if you already operate shared infrastructure.
Silo is externally stateful by default rather than fully stateless. Durable application state lives in PostgreSQL. Redis only stores coordination and cache-style data. Silo still writes transient transcode output locally under /tmp/silo-transcode. If you switch userdb.backend=sqlite, Silo also becomes locally stateful at /var/lib/silo/userdb.
Migrating an existing Continuum Docker install should be done with the preflight helper and cutover guide in docs/continuum-to-silo-docker-migration.md.
Configuration
Silo requires only a DATABASE_URL when running from source or against external infrastructure. In the default Docker Compose path, the stack wires the database and Redis URLs for you. All other settings — libraries, metadata providers, transcoding, users — are managed through the admin UI after first launch.
Server Modes
| Mode | Description |
|---|---|
integrated |
Full server: API + frontend + scanner + transcode (default) |
api |
API server only, no local transcoding |
proxy |
Stream proxy node that connects to the shared deployment database and Redis |
transcode |
HLS transcode worker node that connects to the shared deployment database and Redis |
PostgreSQL Auto-Tuning
The default Docker Compose stack does not require a checked-in postgresql.conf.
It enables Silo's pgtune-style OLTP tuning
by default:
POSTGRES_TUNE: auto
When enabled, Silo connects with DATABASE_URL and applies recommendations with
ALTER SYSTEM, which writes to PostgreSQL's postgresql.auto.conf inside the
database data directory. Reloadable settings are applied immediately with
pg_reload_conf(). Settings that PostgreSQL marks as restart-only are written
too, and Silo logs the setting names so you can restart PostgreSQL once:
docker compose restart postgres
The default Compose database user has the required PostgreSQL permissions. If
you use an external PostgreSQL server, make sure the configured DATABASE_URL
user can run ALTER SYSTEM, or set POSTGRES_TUNE=off and manage
PostgreSQL yourself.
For POSTGRES_TUNE_MEMORY=auto, Silo uses the first trustworthy memory source:
a finite Docker cgroup limit, the read-only /host/proc/meminfo mount supplied
by the bundled Compose file, then /proc/meminfo with container safety guards.
Auto-detected memory is treated as a PostgreSQL budget, defaulting to 75% of
detected RAM so Silo, Redis, plugins, transcodes, and the OS retain headroom.
POSTGRES_TUNE_DB_SIZE=auto queries pg_database_size(current_database()) and
classifies the workload by comparing the database size to that memory budget.
Optional tuning overrides:
| Variable | Default | Description |
|---|---|---|
POSTGRES_TUNE_PROFILE |
oltp |
Tuning profile. Only oltp is currently supported. |
POSTGRES_TUNE_MEMORY |
auto |
Server/container RAM, such as 8GB or 32GB; explicit values are used as-is. |
POSTGRES_TUNE_MEMORY_BUDGET_PERCENT |
75 |
Percent of auto-detected RAM used for PostgreSQL recommendations. |
POSTGRES_TUNE_CPUS |
auto |
CPU count used for worker recommendations. |
POSTGRES_TUNE_STORAGE |
ssd |
One of hdd, ssd, san, or nvme. |
POSTGRES_TUNE_DB_SIZE |
auto |
Use less_ram when the database comfortably fits in RAM, mid_ram, or greater_ram for very large databases. |
POSTGRES_TUNE_CONNECTIONS |
100 |
PostgreSQL max_connections; automatically raised if Silo's app pool is configured higher. |
POSTGRES_SHM_SIZE |
8gb |
Docker /dev/shm size for the bundled PostgreSQL container. |
Advanced operators can still supply their own PostgreSQL configuration or
override these env vars. Set POSTGRES_TUNE=off when you do not want Silo to
change PostgreSQL server settings. Settings already written with ALTER SYSTEM
remain in postgresql.auto.conf; reset those PostgreSQL parameters if you later
move fully to a custom postgresql.conf.
Build from Source
If you prefer running Silo without Docker:
-
Install prerequisites: Go 1.24+, Bun 1.0+, PostgreSQL 18+, and FFmpeg.
-
Start PostgreSQL and Redis (skip if you already have them running)
docker compose up -d postgres redisThe main compose file still expects
MEDIA_ROOTto be set even if you only want the bundled PostgreSQL and Redis services, so set that in.envfirst. -
Configure the database connection
cp .env.example .envEdit
.envand setDATABASE_URLto point to your PostgreSQL instance. -
Build and run
make build ./siloThe server starts at
http://localhost:8080by default. All other settings are configured through the admin UI.
Reporting Issues
If you are reporting a bug, install problem, or performance issue, start with the admin workflow and reproduction steps, not Claude/Codex analysis.
Please include:
- What you were trying to do
- Exact steps you took
- What you expected to happen
- What actually happened
- What exact action is slow or broken (
save,scan,browse,import,playback, etc.) - Whether it happens every time or only sometimes
- The library, media type, filter, setting, or value involved
- Version, branch, commit, and deployment details if you know them
- Screenshots, recordings, or log snippets if relevant
If you used Claude/Codex for debugging, put that under Technical notes at the end. Suspected files, SQL output, stack traces, and root-cause theories can be helpful, but only after the workflow and repro steps are clear.
Use this template:
Goal:
Steps:
Expected:
Actual:
What is slow/broken:
Scope:
Version/branch:
Deployment:
Technical notes:
Contributing & Development
Silo is open source and contributions are welcome. See DEVELOPMENT.md for building from source in a dev workflow, running tests, database migrations, and project layout, and CONTRIBUTING.md for contribution expectations, merge request guidance, and the policy for AI-assisted submissions.
Supporting Silo
Silo is an open-source hobby project, developed in spare time and funded out of pocket. If you'd like to support development, you can sponsor via GitHub Sponsors.
Donations go directly toward the costs of building and running the project:
- AI development tooling subscriptions (Claude, Codex) used to build and maintain Silo
- Push notification relay infrastructure
- Future development costs
Sponsoring is entirely optional — Silo is and will remain free and open source. Bug reports, contributions, and feedback are just as valuable.
License & Trademarks
Silo's source code is licensed under the GNU Affero General Public License
v3.0 or later (AGPL-3.0-or-later) — see LICENSE.
The Silo name, logo, and wordmark are trademarks of Silo Media L.L.C. and are not covered by the AGPL. You're free to fork and redistribute the code, but forks and redistributions must not use the Silo brand as their identity and must remove or replace the brand assets. Publishing a Silo-branded app to an app store requires written permission. See TRADEMARK.md for what's permitted — including referential use like "compatible with Silo."