Media Servers

Bonita’s main integration is Emby: watch history, favorites, newly added media, and collections. Configure the connection under Service settings, then add a webhook and/or run a full sync.

Connect Emby

Open Service settings → Emby API:

1. Server URL, e.g. http://192.168.1.10:8096
2. Username (only this user’s watch/favorite events are processed)
3. API Key
4. Enable, Test connection, then save

The username must match the Emby account you actually use. Webhook events from other users are ignored.

Webhook (live)

The settings page shows the webhook URL for this instance, usually:

http://<bonita-host>:12346/api/v1/webhooks/emby

In Emby: Dashboard → Notifications → Add notification → Webhooks, paste that URL.

Suggested events:

Emby event	Bonita
Playback (stop / scrobble)	Sync progress; mark watched if played to the end
Mark Played	Mark watched
Mark Unplayed	Mark unwatched
Rate (favorite)	Sync favorite on/off
New Media Added	Create the matching media item

If Emby and Bonita are not on the same machine, do not use localhost; use Bonita’s LAN IP or hostname.

Webhooks cover day-to-day updates. The full sync below catches anything that was missed.

Full sync

Two ways:

• Scheduled: every 900 seconds (15 minutes) from the enabled Emby server. Change WATCH_HISTORY_SYNC_INTERVAL in env or config.yaml
• Manual: Tools → Sync Emby watch history

Direction:

• From server (default) — Emby → Bonita. Existing watched/favorite in Bonita are not cleared unless you force
• To server — Bonita → Emby for movies, episodes, and ID-based videos. Clearing watched/favorite on Emby also needs force

Moving from an old Emby to a new one:

1. Sync the old server into Bonita
2. Scrape / ingest the new library so paths or ID numbers match
3. Push from Bonita to the new server

Media items

Media items is the local view of synced titles. Filter by type, watched, favorite, and ID number; you can also create or edit rows.

Matching roughly uses: transfer destination path (same as the Emby item path), then IMDB/TMDB/TVDB, then the ID number. So:

• Keep the output folder as the tree Emby scans
• ID-based titles need a number on the scrape or the record
• Unmatched videos are still created as unlinked items you can fix later

Clean duplicates merges duplicate media items.

Collections

Bonita is the source of truth for synced collections:

1. Add a collection to sync, search Emby box sets, add one (members are pulled once)
2. Pull from server — add members that exist on Emby but not locally; nothing is deleted in Bonita
3. Add or remove members in Bonita (the media item itself stays)
4. Push to server — Emby then matches that list, including removals

Collections you never added to the sync list are left alone.

Next steps

• Tools and advanced
• Basic configuration