Spiel documentation

Overview

Spiel has two halves that work together:

• A server that runs on a machine you own — a Mac, a Linux box, a NAS. It scans your media, fetches artwork, and streams to your devices. Your files never leave your control.
• Apps for Apple TV, iPhone/iPad, and any web browser. They connect to your server and give you a Netflix-style experience over your collection.

An optional Spiel account ties it together: it remembers where you left off across devices and — with a plan — lets you reach your library from anywhere, with no router configuration.

Quick start

1. Install a server on a machine that stays on — see macOS, Linux, or Docker.
2. Open it in a browser at http://<that-machine>:8788 (macOS uses :8789). The server window shows the exact address.
3. Add your media in Settings → Sources: point it at a folder, a NAS share, or a cloud drive, and scan.
4. Sign in (Settings) with your e-mail to sync progress across devices — free.
5. Install an app on your TV or phone, point it at the same server, and press play.

Server — macOS .dmg

Download Spiel Server for Mac, open the disk image, and drag it to Applications. It's self-contained — nothing else to install.

When it runs you get a small window on your desktop (and a Dock icon) showing the server's status, its network address, and Start/Stop controls. The window can be minimized but not closed, so it's always there to come back to.

• Serves on port 8789. Click Copy address to get the URL for your other devices.
• Data lives in ~/Library/Application Support/Spiel Server.
• Apple silicon, macOS 12 or later.

Server — Linux binary

A standalone binary with ffmpeg bundled — nothing else to install. Grab the build for your architecture:

# x86-64
curl -LO https://spielplayer.com/download/spiel-server-linux-amd64.tar.gz
tar xzf spiel-server-linux-amd64.tar.gz
./spiel-server/spiel-server        # serves on :8788

# ARM64 (Raspberry Pi 4/5, ARM servers)
curl -LO https://spielplayer.com/download/spiel-server-linux-arm64.tar.gz

Override the port or data location with SPIEL_PORT and SPIEL_DATA_DIR. Built against glibc 2.31, so it runs on Debian 11+, Ubuntu 20.04+, and equivalents.

Run it as a service

# /etc/systemd/system/spiel.service
[Unit]
Description=Spiel Server
After=network-online.target

[Service]
ExecStart=/opt/spiel/spiel-server/spiel-server
Environment=SPIEL_DATA_DIR=/var/lib/spiel
Restart=on-failure
User=spiel

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now spiel

Server — Docker

Runs on Linux, and on Windows or macOS via Docker Desktop. Mount your media read-only and a folder for the library database:

docker run -d --name spiel -p 8788:8788 \
  -v /srv/spiel-data:/data \
  -v /srv/movies:/media/movies:ro \
  -v /srv/shows:/media/shows:ro \
  ghcr.io/OWNER/spiel-server        # or build from the repo

Then open http://<host>:8788 and add /media/movies and /media/shows as sources. A docker-compose.yml ships in the repo.

Server — Windows .zip

Download Spiel Server for Windows (64-bit), unzip it anywhere, and run spiel-server.exe. ffmpeg is bundled — nothing else to install. It serves on port 8788; the console window shows the address to use from your other devices.

Prefer containers? Docker Desktop works too — see the Docker instructions above.

Media — disks & network shares

In Settings → Sources, add anywhere your files live. Spiel reads filenames, works out what each title is, and pulls posters and metadata automatically.

After adding a source, press Scan. Range-based streaming means Spiel only reads the parts of a file it needs, so seeking is instant even over the network.

Media — Plex, Jellyfin & Emby

Already running a media server? Add it as a source and Spiel plays from its library — handy if you want Spiel's interface and remote access on top of an existing setup. Enter the server URL and an access token or your login, depending on the platform.

Media — cloud drives

Spiel plays straight from cloud storage. In Settings → Cloud drives, pick a provider, sign in, and it appears as a library you can scan — no downloading first.

Supported providers include Google Drive, OneDrive, Dropbox, 阿里云盘 (Aliyun), 115, 夸克 (Quark), 百度 (Baidu), 123, PikPak, MEGA, Yandex, S3-compatible storage, and any WebDAV server (Nextcloud, ownCloud, Synology).

Watching — apps & the web

The apps are in private beta while the App Store releases are finished — request access.

Sign in once, on the server

If you sign your server into a Spiel account, every device that connects to it adopts that identity automatically — so a household signs in once instead of on every TV and phone.

Watching — playback

• Plays everything. MKV, HEVC, multiple audio tracks, embedded and sidecar subtitles. What a device can't decode, the server transcodes on the fly.
• Resume anywhere. Pause on the TV, pick up on your phone — with an account, watch state follows you.
• Made for the couch. Poster rows, scrubber thumbnail previews, skip-intro, and automatic next-episode.
• Subtitles & audio. Switch tracks from the player; your language choices are remembered across episodes.

Accounts & plans

An account is optional — Spiel works on your own network without one. Signing in (with an e-mailed code, no password) adds cross-device resume and unlocks plans.

Plans are purchased in the app. Everything you do at home is free — you only pay to take your library with you.

Away from home

With a Pro plan, your library is reachable over the internet — no router setup, no port forwarding, no dynamic-DNS.

Here's how: your server makes an outbound connection to Spiel's relay, which hands it a public address and keeps track of it. When you open an app away from home, it asks the relay where your server is and connects. Because the connection is outbound, nothing needs to be opened on your router. Video still streams directly between your device and your server — the relay only handles discovery.

Back on your home network, apps automatically prefer the direct local connection, which is faster.

Multiple servers & users

One combined library. Run more than one server — say a NAS and a laptop — and sign both into the same account. Your apps merge them into a single library rather than making you choose.

Separate people. Each account keeps its own sources, settings, and watch history. Two people using the same server see their own setup, not each other's.

Troubleshooting

An app can't find my server

On your home network, make sure the device is on the same Wi-Fi and the server is running. The server window (macOS) or console (Linux) shows the exact address to use. Away from home, remote access needs a Pro plan and the server must be signed into your account.

A cloud drive stopped working

Cookie-based logins expire. Re-authenticate the drive in Settings → Cloud drives.

A file won't play

Most formats transcode automatically. A file that still won't play may use a codec the server's ffmpeg can't handle, or be an incomplete/corrupt file — try it in another player to confirm.

macOS won't open the app

Right-click the app → Open the first time to get past Gatekeeper (the build isn't yet notarized).

hello@spielplayer.com