Watch Party Commands

Host synchronized watch parties (or game nights) with smart timers that automatically detect movie, TV show, and board game titles — whether typed manually or pulled from a Discord event — calculate a runtime/playtime automatically, and track what your community watches together.

Quick FAQ

Q: How does auto-detection work?
A: When you run /timer start in a channel, the bot checks your server's Discord scheduled events. If an event is linked to that specific channel, the bot automatically uses the event's title as the timer label and searches TMDB for runtime.

Q: Does it work with any Discord event?
A: Yes, but the event must be scheduled for the specific channel where you run /timer start. The bot reads the event title to detect what you're watching.

Q: Does runtime detection also work if I type the label myself?
A: Yes. /timer start label:Juno searches the same way an auto-detected label does — no duration needed, the bot looks it up either way.

Q: What if there are multiple matches?
A: The bot shows a selection menu so you can choose the correct title.

Q: Does this work for board games, not just movies and TV?
A: Yes — the bot searches movies, TV shows, and board games (using BoardGameGeek's listed playing time) whenever it's trying to auto-detect a duration.

Q: Can timers auto-stop?
A: Yes! Either set a manual duration (1-600 minutes) or let the bot detect runtime automatically (adds a 10-min buffer).

Q: Who can stop a timer?
A: The person who started it or anyone with moderation permissions.

Q: Does watch history work automatically?
A: Yes! When a timer with a title/label completes, it automatically logs to server watch history. A "Log to Watch History" button also appears for manual override or corrections. For timers without labels, use the button to manually log what you watched. Only the timer starter, administrators, or moderators can use the button.

---

Host synchronized watch parties with timers and track what your community watches.

Announcements

/announce covers the two moments a watch party needs announcing: the advance notice, and the final nudge.

When	Command
An hour or more ahead	/announce party now, or /announce schedule to post it automatically
10 minutes before a scheduled event	Automatic: the starting-soon card
A few minutes before	/announce starting
The moment you start the timer	/timer remind

Every /announce subcommand posts to the channel itself, and all of them are Admin/Moderator only.

The Advance Notice

/announce party title1:<title> time:<time> message:[optional] channel:[optional] role:[optional] episodes1:[optional] title2:[optional] episodes2:[optional] host:[optional] tone:[optional] custom-tone:[optional]

Parameters:

• title1 (required) - First movie or TV show title
• time (required) - Start time to include, used exactly as typed (e.g. "8:00 PM EST")
• message (optional) - Your own announcement text, posted exactly as written. Skips AI entirely
• channel (optional) - Where to post it. Defaults to the channel you run the command in
• role (optional) - Role to ping. Pinged in the message itself, so it genuinely notifies
• episodes1 (optional) - Episode(s) for title1 if it's a TV show — flexible notation: S3E9-E12, S3E9-12, Season 3 Episode 9, S03E09-E12, etc.
• title2 / episodes2 (optional) - A second title, for back-to-back watch parties (e.g. two episodes then a movie)
• host (optional) - Who's hosting — a persona name (like a horror-host character) or a literal @mention, your choice
• tone (optional) - One of Funny, Scary, Dramatic, Wholesome, Mysterious. Only applies to AI-written text
• custom-tone (optional) - Describe your own tone/style instead (e.g. "like a noir detective") — overrides tone if both are given

Which text gets posted:

You supplied	Server AI setting	Result
message	either	Your text, exactly as written. No AI call
nothing	enabled	AI writes it from the real plot and streaming info
nothing	disabled	A plain template

Features:

• Looks up each title on TMDB for the real plot/premise, so AI-written text is specific to the movie or show rather than generic filler
• Automatically includes real streaming availability ("Available to stream on...")
• Uses the title's landscape artwork, which keeps the card about half the height a poster would
• Checks it can actually post in the target channel first, so you're never told an announcement went out when it didn't
• Falls back to a plain template if AI is off or unavailable, rather than failing

Example:

/announce party title1:"Tales From the Crypt" episodes1:"S3E9-E12" title2:"Hellraiser" time:"8:00 PM EST" host:"Cryptkeeper" tone:Scary role:@Movie Night

The Final Nudge

/announce starting message:<text> title:[optional] channel:[optional] role:[optional]

Parameters:

• message (required) - e.g. "Starting in 10 minutes" or "Starting at 9:35 pm". Always posted exactly as written
• title (optional) - What's being watched. Adds the artwork and the canonical title
• channel (optional) - Where to post it. Defaults to the current channel
• role (optional) - Role to ping, in the message content

AI is never involved here — a timing claim is the one thing that must not be paraphrased.

Example:

/announce starting message:"Starting in 10 minutes" title:"Hellraiser" role:@Movie Night

Tip: An unrecognised title won't lose your announcement — it posts with what you typed, just without the artwork.

Scheduled Announcements

Queue the advance notice to post automatically, a set time before one of the server's scheduled events:

/announce schedule event:<pick one> hours:<0-336> minutes:[optional] channel:[optional] role:[optional] message:[optional] title1:[optional] episodes1:[optional] title2:[optional] host:[optional]

• event: start typing and pick from the server's upcoming events, soonest first.
• hours and minutes: how long before the event starts the card should post. For example, hours:2 posts two hours ahead, and hours:0 minutes:45 posts 45 minutes ahead.
• channel: where it posts, such as #announcements. Defaults to the channel you run the command in.
• title1: by default, the event's name is the title (a year like "(1978)" is ignored, and episodes in the name or description, such as "S6: E4-E7", are picked up). Use title1 when the event is called something like "Spooky Saturday".
• The rest work as they do for /announce party. Leave out message and AI writes the text if the server allows it.

It posts the full watch-party card: art, where to stream it, and the start time shown in each reader's own timezone, plus the event's link so people can click Interested.

It's tied to the event:

• Moved: if the event's start time changes, the announcement moves with it.
• Cancelled: if the event is cancelled or deleted, the announcement is cancelled too.
• Late: if the bot was offline through the posting time and the event has already started, the announcement is skipped rather than posted late.

Titles are checked when you schedule, so a typo shows up right away rather than hours later.

See or cancel: /announce scheduled lists what's waiting to post, with a Cancel button for each, and what happened to recent ones (posted, cancelled, skipped, or failed and why).

Example: the full card in #announcements two hours before Friday's event, pinging the movie-night role:

/announce schedule event:Night of the Living Dead hours:2 channel:#announcements role:@Movie Night

The Automatic Starting-Soon Card

Ten minutes before every scheduled event starts, Egg Shen posts a short "starting soon" card in the event's own channel: its voice channel's chat, or the channel named in its location (such as #watch-party). Nobody has to schedule it. It shows the event's cover image (or the title's artwork) and links to the event.

It posts once per event. If the event is moved, it posts again for the new time. Admins can turn it off with /eggshen-config-watch-party watch-party starting-soon.

Timer Reminders

Announce that you're about to start the timer right before beginning the watch party.

Remind Everyone

/timer remind message:[optional] role:[optional]

Parameters:

• message (optional) - Custom message to show (e.g., "Everyone ready?")
• role (optional) - Role to ping/mention

Features:

• Auto-detects from Discord scheduled events - Automatically finds the event linked to the current channel
• TMDB integration - Shows poster, runtime, year, and overview
• Smart buttons - "View on TMDB" and "Join Voice Channel" (if applicable)
• Custom host message - Add your own personal touch
• Role mentions - Ping specific groups to gather everyone
• Pre-timer announcement - Perfect right before running /timer start

Example:

/timer remind message:Everyone ready? Let's go! role:@Movie Night

How It Works:

1. You've already announced the watch party 1-2 hours ago via Discord event
2. Everyone is gathered
3. Run /timer remind to give final notice, showing what you're watching with TMDB details
4. Optionally run /watchparty ready to see who's actually ready (Ready Check)
5. Run /timer start to begin

Tip: Use this right before starting the timer so everyone knows what's playing.

Ready Check

Not sure whether everyone's back with snacks? Ask, and let the bot count. It works for a planned watch party or a spur-of-the-moment one.

/watchparty ready message:[optional] role:[optional]

Parameters:

• message (optional): a line shown on the card, such as "Starting in 5!"
• role (optional): a role to ping

The bot posts a card with two buttons, ✅ Ready and ⏳ Need a minute. Anyone can press one, and can switch their answer at any time. The card lists who's ready and who asked for a minute, so you can see exactly who you're waiting on. It's only a count; you still start the timer yourself.

When a watch party is scheduled for the channel, either already running or starting within about two hours, the card also compares the answers with who marked the Discord event Interested:

👀 Interested in the event: 9
4 ready, 1 needs a minute
Not checked in yet: @hal @ivy @jo @kim
Also ready: 1 who didn't mark Interested

The Interested list refreshes as people answer, so someone who clicks Interested late still counts. Without an event, or if the bot can't read the event, the card is a plain tally.

You'll get a ping when the last person who asked for a minute presses Ready: "✅ Everyone who asked for a minute is ready." It's a new message, so it notifies you even if you're not looking at the card.

The card stops taking answers and freezes with the final count when:

• A timer starts in the channel (/timer start)
• The channel's Discord event goes live, if the check was posted before it started. The card updates the next time someone presses a button.
• You close it with /watchparty ready-close
• Someone posts a newer ready check in the same channel
• Three hours pass

Close a Ready Check

/watchparty ready-close

Stops taking answers on the channel's ready check and shows the final count. Only the person who posted it, or a moderator, can close it.

Timer Commands

Start simple stopwatch timers for watch parties.

Start a Timer

/timer start label:[optional] movie:[optional] tv:[optional] duration:[optional] theme:[optional]

Parameters:

• label (optional) - Label for what you're watching (e.g., "Movie night", "The Matrix"). Also triggers a movie/TV/board-game runtime lookup — see below
• movie (optional) - Movie title to look up and time automatically. An alternative to label for when you specifically mean a movie — skips the ambiguous merged search and goes straight to a movie-only lookup
• tv (optional) - TV show title to look up, optionally with an episode or episode range (e.g. "The Office" or "Tales from the Crypt S5E5-E8") — an alternative to label for TV specifically
• duration (optional) - Duration in minutes (1-1440) for auto-stop timer — used exactly as given by default (see Timer Durations & the Expiry Warning below for the one case where the bot picks a duration for you)
• theme (optional) - Timer countdown theme (default: modern)
  • modern - Colorful animated countdown (default)
  • classic - Sequential text countdown like the original bot

Use only one of label, movie, or tv — providing more than one is rejected with an error, since each is a different way of saying what's playing. label still works exactly as it always has (including auto-detecting from a channel's linked event, and searching movies/TV/board games together) — movie/tv exist for when you already know the type and want to skip the ambiguity, e.g. if a movie and a TV show happen to share a name.

Features:

• Discord Event Auto-Detection: Bot checks server's scheduled events - if one is linked to the current channel, automatically uses event title as timer label
• Auto-stop: Set duration to automatically stop timer when time expires
• Runtime auto-detection: Whenever a label is set and no duration is given — whether typed manually or auto-detected from a Discord event — the bot searches movies, TV shows, and board games and adds a 10-minute buffer to whatever it finds. A found runtime is used as-is, no matter how long it is
• Multi-episode watch parties: A label like "Tales from the Crypt - S5: E5 - E8" (four episodes in one watch party) is understood automatically. The episodes can also live in the scheduled event's description — an event named "Tales From the Crypt" described as "Season 6 episodes 4 - 7" produces a correct 113-minute timer with no clicks — see Multi-Episode Watch Parties below
• Decisive auto-selection: When a search turns up an exact title match, or a clear decisive best match, the bot skips the confirmation menu and starts the timer directly — same landslide-detection behavior used by /movie and /tv
• No duration guessed for TV without an episode count: A TV show's listed runtime is a single episode, but a watch party is rarely one episode — so that number would stop the timer partway through. A TV title gets a real duration only when the episodes are known (from range notation, or the event description); otherwise the timer runs to the server's auto-stop limit, which warns before it ends so anyone can extend it
• Start now, or look it up: If an auto-detected title can't be pinned down, the bot offers two buttons — ▶️ Start Now or 🔎 Look Up Title — rather than a long list. Servers can change this with /eggshen-config-watch-party watch-party auto-detect
• Smart selection: When you do ask to look up a title (or a label you typed yourself is ambiguous), a selection menu appears with ▶️ Start Timer Without Title Selection as its first option, so starting immediately is always one click away
• No match found: If nothing is typed and nothing is auto-detected at all, the bot tells you directly and falls back to a default duration (6 hours, server-configurable) rather than running forever unnoticed — see below
• Recovery from a bad auto-detected title: If the event title the bot pulled from a Discord scheduled event doesn't match anything, you're never stuck with the wrong title — a 🔎 Search button lets you type the correct one and search again, as many times as needed — see Auto-Detection Example below
• Automatic watch history logging: When timer completes (manual or auto-stop), automatically logs to server watch history if title found on TMDB
• 5-second countdown before starting (with visual/text animation)
• Public display visible to all channel members
• Shows remaining time when duration is set

Examples:

/timer start label:The Lord of the Rings duration:190
/timer start label:Movie Night theme:classic
/timer start movie:The Thing
/timer start tv:The Office
/timer start tv:"Tales from the Crypt S5E5-E8"
/timer start duration:30
/timer start

Auto-Detection Example:

1. Create a Discord scheduled event named "The Lord of the Rings"
2. Set the event location to a specific voice/stage channel (e.g., #watch-party)
3. In that channel, run /timer start (no label parameter needed)
4. Bot detects the Discord event linked to this channel
5. Bot uses "The Lord of the Rings" as the timer label automatically
6. Bot searches TMDB and finds multiple matches, shows selection menu
7. Select the correct movie (e.g., "The Fellowship of the Ring")
8. Bot auto-detects 178 min runtime + 10 min buffer = 188 minutes
9. Timer starts with auto-stop at 188 minutes

Tip: This works for any Discord event linked to a channel - the bot will always check for events when you run /timer start without a label! Typing a label yourself (/timer start label:The Fellowship of the Ring) gets the same title search and auto-duration treatment, without needing a Discord event at all.

If the auto-detected title doesn't match anything (or matches too many things): Since the title came from the scheduled event's name rather than something you typed, it won't always match cleanly — a typo in the event name, a subtitle TMDB doesn't recognize, etc. Rather than starting a timer under the wrong name (or leaving you stuck), the bot always gives you a way out when the label came from auto-detection:

• No matches at all: Instead of silently starting the timer under the unresolved event title, you'll see a screen with two buttons — 🔎 Search (opens a box to type the correct title, which searches again) and ▶️ Start Timer (starts the timer anyway, with no duration — see Timer Durations & the Expiry Warning for what that means).
• Multiple matches (the usual selection menu): The same 🔎 Search button appears alongside the picker, in case none of the listed results are actually right.

You can click Search as many times as you need — there's no limit — until either a search finds the right title or you choose Start Timer to proceed without one. This recovery flow only appears for auto-detected titles; a label you typed yourself with label:/movie:/tv: keeps the existing behavior (a ▶️ Start Timer Without Title Selection option at the top of the picker, or a quiet warning and immediate start when nothing matches at all).

Multi-Episode Watch Parties

A label that includes a season/episode range — like an event or channel name of "Tales from the Crypt - S5: E5 - E8" — is understood as a single watch party spanning multiple episodes, not a single-episode lookup. The bot:

1. Recognizes the range notation and separates it from the show name
2. Searches for the show (using the same decisive auto-selection and AI-powered ranking as /tv)
3. Looks up every episode in the range and adds up their individual runtimes
4. Adds the standard 10-minute buffer to the total

Rather than just showing a final number, you'll see a breakdown so you can sanity-check it before the timer starts:

📺 Tales from the Crypt — Season 5, Episodes 5-8 (4 episodes)
  E5: 22 min
  E6: 22 min
  E7: 21 min
  E8: 23 min
──────────────
4 episodes, ~22 min each = 88 min + 10 min buffer = 98 min

If TMDB doesn't have a specific runtime for one of the episodes, the show's average episode length is used for that one instead, and it's marked (estimated) in the breakdown so it's clear which numbers are exact and which are a best guess.

Supported formats: S5E5-E8, S5: E5 - E8, S05E05-E08, Season 5 Episode 5-8, Season 5, Episodes 5-8, and single-episode notation (S3E1, 3x11) all work — a single episode with no range just gets the normal single-episode treatment.

If the show name matches multiple shows (e.g. a same-titled reboot), you'll get a selection menu just like the regular multi-match picker — pick the right one and the range calculation continues from there.

Check Timer Status

/timer status
/timer check

Answers the one question people actually ask — how far in are we — in two lines:

⏱️ Timer: The Covenant (2006)
Elapsed: 2h 43m 32s    Duration: 1h 47m

Elapsed time carries seconds, since that's the number people sync a watch party against.

Duration only appears when the bot actually knows the runtime — from a title lookup or a duration you typed. A timer running on the server's auto-stop cap shows elapsed time alone: that cap is a backstop against a timer running forever, not a statement about how long the film is, and showing it would answer "when does this end?" with an unrelated number. A paused timer says so.

Parameters:

• public (optional) - Show this to everyone in the channel (default: true — set false to keep it to yourself)

Status is public by default: a watch party is a shared activity, and whoever asks is usually asking on everyone's behalf. If you'd rather check quietly:

/timer status public:false

/timer check is an alias for /timer status and works exactly the same way, including the public option.

Name a Running Timer

/timer title <title>

Names a timer that was started without identifying what's playing — which is what the watch-history entry gets written under when it stops — and sets the timer's duration from the title's runtime.

Who can use it:

• While the timer has no title, anyone can set one. That's the state worth fixing, and whoever's watching can fix it
• Once a title is set, only the person who started the timer or a moderator can change it — overwriting a correct title would quietly corrupt the watch-history entry

It searches like /movie and /tv: a clear match is used right away, and episode notation works too:

/timer title The Thing
/timer title Tales from the Crypt S6: E4-E7

If the title could mean more than one thing ("Fargo" is two films and a show), or what you typed isn't an exact title, you get a picker of movies and shows to choose from, with exact title matches listed first. The first option, Keep "…" as typed, names the timer without matching it to anything. Only if TMDB finds nothing at all is the timer named with your text directly, since an approximate label beats an unnamed one. The change is announced in the channel with a Now Watching card (art, year, synopsis, and where the timer stands), since it was made on everyone's behalf.

It sets the duration, counted from when the timer started. The timer was started when playback was, so the runtime includes the time already run: 20 minutes into a 100-minute film, the duration becomes 1h 50m (the runtime plus the usual 10-minute buffer) with about 90 minutes left. Time spent paused never counts. The duration stays as it was when:

• It's a show with no episodes given. One episode's runtime would end a multi-episode party early; include them (Show S1: E1-E3) to set one
• Someone else set the duration. Anyone can name an unnamed timer, but only the person who started it or a moderator can replace a duration they chose. A timer that only has the server's safety-net duration can be filled in by anyone
• The timer has already run past the runtime

Use /timer adjust to set a duration by hand.

Pause and Resume Timer

/timer pause
/timer resume

Pause a timer if something comes up — a break, a technical issue, anything that interrupts the watch party — without losing your elapsed time or restarting from scratch.

• /timer pause freezes the elapsed and remaining time and cancels the pending auto-stop. /timer status will show "Timer Paused" with the elapsed/remaining time held at exactly where they were when you paused.
• /timer resume picks up right where you left off — the remaining time (if a duration was set) continues counting down from the same point, and auto-stop is rescheduled accordingly. Time spent paused never counts against the timer's duration.
• A paused timer survives a bot restart — it stays paused and won't auto-stop or start counting down on its own until you /timer resume it.
• /timer stop still works normally on a paused timer.
• /timer adjust requires resuming first — you can't change the duration while paused.
• By default, only the timer starter, server administrators, or moderators can pause/resume it — same permissions as /timer stop. Servers can open this up to everyone (see below).

Stop Timer

/timer stop

Stops the current timer in the channel. By default, only available to:

• User who started the timer
• Server administrators
• Users with Manage Guild permission
• Users with Moderate Members permission

Who Can Pause, Resume, or Stop a Timer

By default, pausing, resuming, and stopping a timer is restricted to whoever started it plus server administrators/moderators. Some servers — especially larger, more casual ones — prefer to let any member step in and pause or stop a timer, since the person who started it isn't always still around when something comes up. Admins/mods can enable this:

/eggshen-config settings timer-control anyone-can-pause-stop:true

This only affects /timer pause, /timer resume, and /timer stop — /timer adjust and /timer autostop (which change the timer's duration or auto-stop configuration, not just start/stop it) always stay restricted to the starter or an admin/mod, regardless of this setting.

Adjust Timer Duration

/timer adjust duration:<minutes>

Changes the total duration of the active timer (elapsed time is preserved — this sets a new total, not an amount to add). Same permissions as /timer stop. Used exactly as given by default; only reduced if this server has opted into a timer ceiling (off by default).

Enable or Disable Auto-Stop

/timer autostop autostop:<enable|disable> duration:[required if enabling]

• autostop:disable — removes auto-stop entirely from a running timer, so it never stops on its own. Use this for overnight sessions or marathons where you don't want any cap.
• autostop:enable — turns auto-stop back on for a timer that doesn't currently have a duration; requires a duration.

Same permissions as /timer stop.

Timer Durations & the Expiry Warning

By default, a timer runs for exactly whatever duration you gave it — no cap, no maximum. A manually-typed duration:500 or an auto-detected 8-hour concert film runs for its full length; nothing shortens it unless this server has explicitly opted into a timer ceiling (off by default).

The one exception is when nobody said anything at all — no duration was typed, no label was given (or the label matched nothing), or you chose "Skip" from the title-selection menu. In that specific case, rather than the timer running forever unnoticed, it falls back to a default 6-hour (360 minute) duration, so it still auto-stops eventually. This fallback duration is invisible in /timer status and the start confirmation — no "Duration" or "Remaining Time" field is shown, since it isn't something you set or the bot determined, just a safety net running quietly in the background. It's server-configurable:

/eggshen-config settings max-timer-duration minutes:<1-1440>
/eggshen-config settings max-timer-duration unlimited:true

unlimited:true disables the fallback entirely — a no-duration timer just runs forever, same as /timer autostop disable. See Configuration for details.

About an hour before one of these fallback-duration timers is due to auto-stop, the bot posts a warning in the channel, mentioning whoever started it, with an Extend Timer button. Clicking it opens a small form to enter how many additional minutes to add. Once extended, the timer's duration is a real, user-chosen value from that point on — it won't warn again unless it's later extended and re-enters the last-hour window.

This warning only ever fires for fallback-duration timers. A timer with a real duration — typed manually, adjusted with /timer adjust, or auto-detected from a movie/TV runtime — never gets this warning, no matter how long it runs.

/timer autostop disable remains the way to start a timer with no expiry at all from the outset.

Watchlist

The server's queue of what to watch next — the step between deciding on something and actually watching it.

Adding titles

/watchlist add title:<title> note:[why you want to watch it]

Searches TMDb for movies and TV shows. If several titles match, pick the right one from the menu. A title already on the list can't be added twice.

Example:

/watchlist add title:The Thing note:Kurt Russell double feature?

Viewing the list

/watchlist list filter:[all|movie|tv] sort:[recent|oldest|votes]

Shows who added each title, any note, and how many people have voted for it. Sort by Most wanted to see what the server actually wants, or Longest waiting to surface things that have been sitting there.

Voting for what to watch

/watchlist want title:<title>

Registers that you want to watch something. Run it again on the same title to take your vote back. Votes drive the Most wanted sort and the votes pick method.

Picking something to watch

/watchlist pick method:[random|votes|oldest] filter:[movie|tv]

Chooses one title and shows it with its poster. random is the argument-settler; votes picks the most wanted; oldest picks whatever has waited longest.

Removing titles

/watchlist remove title:<title>

Anyone can remove a title they added themselves. Removing someone else's addition requires moderator permissions. Moderators can also empty the list entirely with /watchlist clear.

How the watchlist connects to everything else

• Watching something removes it. Logging a title with /watched add — or letting a watch party timer log it automatically — drops it from the watchlist. Turn this off with auto-remove-watched.
• Tournament winners can be added automatically. With auto-add-champion enabled, a finished /bracket tournament puts its champion straight on the list, tagged with the tournament it won. Off by default, and only applies to movie and TV tournaments (games, board games and books aren't TMDb-backed).

Watchlist settings

/eggshen-config-watch-party watchlist settings
/eggshen-config-watch-party watchlist view

Setting	Default	What it does
max-size	100	Maximum titles allowed on the list (10–500)
mod-only-add	Off	Restrict adding to moderators
auto-add-champion	Off	Put tournament winners on the list automatically
auto-remove-watched	On	Remove a title once it's logged as watched

Watch History

Track what your server community watches together.

Automatic Watch History Logging

NEW: Timers now automatically log to watch history!

When a timer with a title/label completes (via /timer stop or auto-stop):

1. Bot searches TMDB for the title
2. Finds best match (first result)
3. Automatically logs to server watch history
4. Shows confirmation with poster, title, year, type
5. "Log to Watch History" button appears for manual override

For timers WITHOUT labels:

• Button appears to let you manually add what you watched
• Click button → Enter title → Add optional notes → Submit

Button Permissions:

• ✅ Timer starter can use it
• ✅ Server administrators can use it
• ✅ Server moderators can use it
• ❌ Other users cannot log timers they didn't start

Information Saved:

• Movie/TV show title from TMDB
• Year and type (movie/TV)
• Date watched
• Channel where watched
• Who started the timer
• Who stopped the timer
• Timer duration as notes
• Poster image

What You See (with label):

⏹️ Timer Stopped & Logged 🛑📝

The Lord of the Rings: The Fellowship of the Ring (2001)

✅ Automatically logged to watch history

Total Time: 3:02:15
Type: Movie
Channel: #movie-night
Started by: MovieFan
Stopped by: MovieFan

[📝 Log to Watch History] ← Click to manually log again or correct

What You See (without label):

⏹️ Timer Stopped 🛑

Timer has been stopped

Total Time: 2:15:30
Started by: MovieFan
Stopped by: MovieFan

[📝 Log to Watch History] ← Click to add what you watched

No TMDB Match? If the title isn't found on TMDB, you'll see a warning but the button will still appear so you can manually search and log.

Manual Override: The button lets you log a different title if auto-detection picked the wrong result, or add custom notes to the entry.

Manual Watch History Entry

/watched add title:<title> notes:[optional notes]

Parameters:

• title (required) - Movie or TV show title to search for
• notes (optional) - Additional notes about the viewing
• private (optional) - Only show the confirmation to you instead of the whole channel (default: false)

Features:

• Search integration for accurate titles
• Selection menu if multiple matches found
• Immediate save to server history
• Public announcement in channel (unless private:true)

Example:

/watched add title:Big Trouble in Little China notes:Great kung-fu scenes!

View Watch History

/watched history filter:[type] limit:[number]

Parameters:

• filter (optional) - Filter by content type (all, movie, tv) - default: all
• limit (optional) - Number of entries to show (1-25) - default: 10

Displays recent watch history for the server:

• Titles with TMDB links
• Dates watched
• Channels where watched
• Who saved each entry
• Notes from viewers

Examples:

/watched history
/watched history filter:movie limit:25
/watched history filter:tv limit:5

Watch Party Best Practices

Before Starting

1. Coordinate with your community on what to watch
2. Ensure everyone has access to the content
3. Set clear start time expectations
4. Test audio/video sync beforehand

During the Watch Party

1. Use the timer to keep everyone synchronized
2. Encourage discussion in text chat
3. Avoid spoilers for new viewers
4. Pause timer if taking a break

After Watching

1. Log to watch history while discussing
2. Add notes about memorable moments
3. Take recommendations for next watch party
4. Review watch history to avoid repeats

Watch History vs Personal Ratings

Important: Watch history is server-level tracking, not personal ratings.

• ✅ Public record of what was watched together
• ✅ Channel tracking shows where watch parties happen
• ✅ Community feature visible to all members
• ❌ Not for personal ratings or private tracking
• ❌ Not user-specific - saved by timer starter/mods

For personal tracking, use external services like:

• Trakt.tv
• Letterboxd
• TV Time

Rate Limiting

Watch party commands have minimal rate limiting:

• Timer commands: Once per minute per channel
• Watch history: Normal rate limit applies
• Logging from button: No cooldown (permission-based)

Troubleshooting

Can't log to watch history

• Verify you started the timer OR have mod permissions
• Check that timer has completed
• Ensure watch history isn't disabled for the server

Timer not starting

• Check for existing timer in the channel
• Verify bot has permission to send messages
• Ensure duration format is correct

Can't find title when logging

• Use /movie or /tv commands first to verify title
• Try alternative title formats or release years
• Check that TMDB API key is configured

Watch history not saving

• Verify bot has database access
• Check server configuration for watch history
• Review mod logs for error messages