Events tell you what was observed. Episodes show you what happened.
Episode turns camera, doorbell, sensor, and automation alerts into one incident timeline. When something happens, it can record every relevant camera in the same physical Area and present the Events, snapshots, and video together as a single Episode.
It is self-hosted and local-first. Instead of leaving you with disconnected alerts and clips, Episode preserves the original material, records where it came from, and keeps the whole incident portable.
- One incident, multiple camera views. A doorbell, camera, sensor, or automation can start recording across the relevant Area.
- Evidence stays original. Raw deliveries, snapshots, and recordings are preserved and checksummed; overlays and future AI results remain derived.
- Local and portable. Data remains on your infrastructure, and every Episode has a self-contained directory, manifest, and journal.
- Standards first, vendor enhancements second. ONVIF provides the primary camera path, while plugins add richer vendor-specific capabilities.
- Built to extend. A versioned plugin API lets integrations evolve without putting vendor logic into the core.
| Source | Current support |
|---|---|
| ONVIF cameras | Discovery, media profiles, RTSP, snapshots, and optional Events |
| Hikvision | ISAPI, Alarm Server, FTP snapshots, and optional HCNetSDK |
| Reolink | Baichuan discovery, media, snapshots, and subscribed Events |
| Local automations | Raw-first HTTP Event API |
Episode can start Area-wide multi-camera recording, stream active HLS captures, show current camera views, correlate snapshots and detection regions, switch capture participation profiles, and send an Episode-start webhook or Discord notification. A profile (or a single camera) can also filter event classes — plain motion, device status, audio, tamper and video loss, classified detections and wired alarm inputs, access records — so they stop opening Episodes by themselves. Nothing is filtered until you name its class, every class is available at both levels, and a filtered Event is still preserved and attributed to the Episode that was already open.
You need Docker with the Compose plugin. Clone the repository or download a release source archive, then run:
cp episode.example.json episode.json
cp .env.example .env
mkdir -p data pluginsBefore starting, replace the example FTP password in episode.json, or disable
the FTP connector if you do not need uploads. FTP is enabled in the example and
its published ports bind to all host interfaces by default. Set EPISODE_UID
and EPISODE_GID in .env to a user that can write data/. Review the
network bindings before allowing access.
docker compose --env-file .env pull
docker compose --env-file .env up -dOpen http://localhost:8989. The guided setup will help you:
- create an Area;
- add and validate a Device;
- choose its recording behavior and integrations;
- confirm the Evidence retention policy.
Areas, Devices, capture profiles, retention, notifications, and other operator settings are managed from the UI and apply without restarting the container.
These commands run the image pinned in .env, not changes in your checkout.
Use matching release documentation and examples; see source development
to run your own edits.
See the installation guide for network access, upgrades, native plugins, and troubleshooting.
Warning
Episode does not currently provide authentication. Keep it on a trusted network or behind a trusted access layer. The default Docker configuration binds the web interface to localhost.
- A connector receives a camera, sensor, or automation delivery.
- Episode preserves the exact input and records how it arrived.
- A configured plugin interprets it as a vendor-neutral Event.
- The core correlates related Events into an Area-scoped Episode.
- Episode starts or extends configured actions such as camera recording.
- The UI presents the resulting timeline and Evidence together.
The core decides correlation and actions; transports receive bytes; plugins interpret protocols. This separation keeps Episode vendor-neutral and prevents one integration from owning the incident model.
Episode 0.1.0-beta.9 is a working public beta for technical self-hosters using
IP cameras and Docker. Current priorities are reliable preservation, correct
correlation, simple operation, and an uncluttered Episode-first interface.
Authentication, general policy evaluation, AI processing, high availability, and compatibility with every camera implementation are not complete. Device capabilities are detected rather than assumed, and the beta plugin API remains versioned for external contributors.
Start with the documentation map for reading paths, a short glossary, and guidance on which reference to use. Contributors can start with the development guide.
- Installation and troubleshooting
- Using and operating Episode
- ONVIF setup
- Hikvision setup
- Reolink setup
- Generic Event API
- Plugin authoring
- Architecture and domain model
- REST API v1
- Security
- Contributing
The open-source organization is OpenEpisode; the product is Episode.
Brand assets are available in brand/.
Episode is released under the MIT License. If it is useful to you, you can support its continued development through PayPal.Me. Contributions are appreciated but never required.