EventSnap/docs/CONCEPT_DIASHOW.md

Live Diashow Concept

Status: SHIPPED. Implementation lives at frontend/src/lib/diashow/ and frontend/src/routes/diashow/+page.svelte. Treat this doc as the design reference; code is the source of truth.

Goal

A fullscreen, auto-advancing slideshow that any user can start from their device. Suitable for a venue projector or TV running off a single phone/laptop. Two behaviours combine in one view:

1. Live drain — when a new post is uploaded mid-event, it appears on the next slide transition.
2. Shuffle fallback — between new uploads (and they will be rare in quiet stretches), the diashow rotates through everything posted so far, in shuffled order.

The user does not need to be Host or Admin. Any guest can start the diashow on their own device. There is no global "the room's diashow" — each device runs its own (though they will look very similar if started at the same time).

---

Behavioural model

Two FIFO queues live in the client:

Queue	Source	Drain priority
liveQueue	SSE events for new processed uploads	First
shuffleQueue	Snapshot of all known uploads, shuffled	When live empty

Slide-advance algorithm

function nextSlide(): Slide | null {
  // 1. Drain live posts first (FIFO).
  if (liveQueue.length) return liveQueue.shift()!;

  // 2. Refill shuffle queue from `allKnown` if drained.
  if (!shuffleQueue.length) {
    shuffleQueue = shuffle(
      [...allKnown.values()].filter(s => !recentlyShown.has(s.id))
    );
  }
  return shuffleQueue.shift() ?? null;
}

A small ring buffer recentlyShown (last ~5 IDs) prevents the same picture coming back within seconds when the shuffle queue is rebuilt.

Live insertion

sseClient.on('upload-processed', (msg) => {
  if (allKnown.has(msg.upload_id)) return;
  const slide = await fetchUpload(msg.upload_id); // or use payload directly
  allKnown.set(slide.id, slide);
  liveQueue.push(slide);
});

Listen on upload-processed, not new-upload — the preview/thumbnail must exist before we try to display the slide.

Deletion / hiding

sseClient.on('upload-deleted', ({ upload_id }) => {
  allKnown.delete(upload_id);
  liveQueue   = liveQueue.filter(s => s.id !== upload_id);
  shuffleQueue = shuffleQueue.filter(s => s.id !== upload_id);
  if (currentSlide?.id === upload_id) advanceImmediately();
});

Hidden uploads (banned user with uploads_hidden=true) need either a new SSE event or to piggyback upload-deleted for diashow purposes. Simplest path: emit upload-deleted for hidden posts to all subscribers (the live feed already filters them via v_feed, so this is a backwards-compatible signal).

---

Initial pool

On start:

1. Call GET /api/v1/feed?limit=200 (or paginate-and-drain in the background while the diashow runs).
2. Push every returned upload into allKnown.
3. Build the first shuffleQueue from it.
4. Open the SSE stream and route upload-processed / upload-deleted into the queues.

If the event is empty, show a friendly placeholder: "Noch keine Beiträge — neue erscheinen automatisch."

---

Frontend surface

Entry point

A small Diashow / "Präsentation starten" action visible:

• In the feed header (icon next to the list/grid toggle) on tablet/desktop layouts.
• In the Account page on mobile (less prominent — diashow is primarily a venue-screen feature).

Tapping it navigates to the /diashow route (full-screen, bottom nav hidden).

Route: /diashow

• Fullscreen request via element.requestFullscreen() after first user gesture.
• Screen Wake Lock: navigator.wakeLock.request('screen') to keep the screen on during long shows. Renew on visibilitychange if needed.
• Default dwell: 6 seconds per slide. Configurable via overlay control: 3 / 6 / 10 s.
• Tap or Escape reveals an overlay with: pause/resume, dwell selector, transition picker, exit.
• Transitions: crossfade (≈400 ms) by default; Ken Burns, zoom, slide, etc. available as pluggable components — see "Pluggable transitions" below.
• Videos: autoplay muted, fit-to-screen, advance on ended or after max(dwell, 12 s), whichever first.
• Preload the next slide's media into a hidden <img>/<video> to avoid flashing.
• Media source respects the user's data mode (see FEATURES.md §2.5). In Saver mode the diashow loads preview_url; in Original mode it loads the original. The data-usage warning is shown once when the mode is toggled in My Account — the diashow itself stays silent.

Pluggable transitions

Each transition is a drop-in Svelte component under frontend/src/lib/diashow/transitions/ (path finalised at implementation time). The interface is intentionally tiny:

// pseudocode — the real shape lands with the feature
export interface SlideTransition {
  id: string;                  // 'crossfade', 'kenburns', ...
  label: string;               // shown in the dwell/transition picker
  durationMs: number;          // default; can be overridden per-event
  // The actual motion is implemented by mounting the component with `from` / `to` slides.
}

A small registry maps id → component; the settings popover renders that registry as a dropdown. Adding a new animation is one new file plus one line in the registry — no other changes required. This is the maintainability target called out in FEATURES.md §2.9 and IDEAS.md ("Animation pack").

The same pattern is a candidate for whole-event "themes" later — a bundle of (transition

• dwell + optional background-music defaults).

Edge cases

Case	Behaviour
Empty event	Placeholder card; live SSE will trigger the first show
All known uploads are still compressing	Same placeholder — wait for upload-processed
Network drop / SSE reconnect	EventSource auto-reconnects; queues survive
Current slide gets deleted	Advance immediately
Event is closed (no new uploads possible)	Diashow keeps running on shuffle queue indefinitely
Banned user's content (uploads_hidden)	Removed via upload-deleted signal (see Deletion)

---

Backend changes

Essentially none. The diashow reuses:

• GET /api/v1/feed (initial pool)
• GET /api/v1/stream SSE (upload-processed, upload-deleted)

Optional small additions:

1. Emit upload-deleted (or a new upload-hidden) when a host bans a user with hide_uploads=true, so that diashow clients can scrub the relevant slides without reloading.
2. Consider raising the cap on GET /api/v1/feed?limit= for diashow clients (or paginate the initial pool in the background — preferred, no API change needed).

---

Future extensions (not in scope for v1)

The big ones live in IDEAS.md under "Diashow extensions" — most notably the global / synchronised diashow where multiple screens share one server-side cursor. Short list of others kept here for context:

• Curated highlights mode — only show uploads tagged with a specific hashtag, or Host-pinned "Story" uploads (depends on the story-highlights feature).
• Audio bed — host can pick a background track; mute videos so they don't fight the music.
• Slide caption / uploader chyron — small lower-third with the uploader's name and caption. Out by default to keep the visual clean.