Skip to content
OpenEpisodePublic

About

Events tell you what was observed. Episodes show you what happened.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Episode

Episode

Events tell you what was observed. Episodes show you what happened.

CI Latest release Container image MIT license

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.

Why Episode?

  • 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.

What works today

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.

Quick start

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 plugins

Before 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 -d

Open http://localhost:8989. The guided setup will help you:

  1. create an Area;
  2. add and validate a Device;
  3. choose its recording behavior and integrations;
  4. 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.

How it works

  1. A connector receives a camera, sensor, or automation delivery.
  2. Episode preserves the exact input and records how it arrived.
  3. A configured plugin interprets it as a vendor-neutral Event.
  4. The core correlates related Events into an Area-scoped Episode.
  5. Episode starts or extends configured actions such as camera recording.
  6. 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.

Project status

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.

Documentation

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.

The open-source organization is OpenEpisode; the product is Episode. Brand assets are available in brand/.

Support and license

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.

About

Events tell you what was observed. Episodes show you what happened.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages