ace · agentic cue experience

v1.5.3

Get to a working dashboard in five minutes.

1 · Quick start

Install the app, walk through the 60-second wizard, hit Start. ACE listens to the room and pushes the right slide automatically — no clicking through cues during the service.

Install

1. Mount the DMG and drag ACE.app into /Applications.
2. Eject the disk. Open ACE from /Applications (not from the DMG).
3. First launch takes 10–30 seconds while the bundled AI model warms up.

First-run wizard

Five steps: Welcome → Backend ready → Speech model → macOS permissions → Done. Each step has a What's happening? expander if you want the technical detail.

The wizard handles the Whisper model download and routes you through Mic and Screen-Recording permission requests with deep-links to System Settings.

Start the service

1. Click Start in the top-left of the toolbar. ACE begins listening.
2. Sing or speak something the system knows. With a song library imported, lyrics auto-push to PROGRAM.
3. To send to a real audience screen, open Screen Configuration with ⌘+⇧+S.

ace · agentic cue experience

v1.5.3

A map of every panel and what it does.

2 · The dashboard

Toolbar — left side

• Start / Stop — toggles AI listening.
• Audio visualizer — a traffic light on your input level: amber + slow pulse means too quiet, green means good signal, red means peaking.
• Auto / Song / Bible — detection mode picker. Auto detects either; Song-only locks to lyrics; Bible-only locks to scripture.
• Live / Hold — Live pushes detected matches to PROGRAM. Hold pauses auto-display (useful between songs).
• Confidence ± — tweak the AI threshold during a service.

Toolbar — center (workflow modes)

Toolbar — right side

• Import — unified wizard for Bibles, songs, slides (PPTX / Keynote / PDF / image-sequence) and audio.
• ⚙ Settings — direct nav to the Settings page.
• Audio visualiser — see toolbar-left.

Sidebar (left)

Library of imported content: songs, presentations, Bibles. Drag to reorder; the order becomes the day's Service Plan.

Center column

• Show — current and next song-section cards, live transcript, scripture, slide thumbnails.
• Edit — full lyric / section editor (slide-grid layout in v1.5.3).
• Bible — verse-context view.

Right panel

• Preview / Program — what's queued (Preview) and what's live (Program). Operators drive most of the service from here.
• Macros — operator-fired automations (clear all, switch look, blank).
• Sermon Notes — sermon recording with auto-detected scripture references.

Media Bin (bottom dock)

Playlists, asset library, single-click trigger, layer / fit, Stock Bin filter (Pixabay if configured). Drag a media item onto the slide preview to make it the audience background.

ace · agentic cue experience

v1.5.3

3 · Importing content

⌘+I or click Import in the toolbar. One wizard for everything you bring into ACE — songs, Bibles, slides, audio.

Six-stage wizard

Supported formats

LibreOffice deferred-install

The first PPTX import on a Mac without LibreOffice triggers an in-app installer with a SHA256-verified download from dl.ace-presenter.app/libreoffice/26.2.3/. Approximately 280 MB per architecture; approve once and future imports use the bundled install.

ace · agentic cue experience

v1.5.3

4 · Themes and Looks

ACE separates how things look (Theme — fonts, colors, background) from what's enabled (Look — which layers render on which screens).

Themes (Theme tab)

A theme defines: font family, size, weight and color; subtitle color; background mode (solid / gradient / image); text shadow; position; margins; line-reveal speed.

• Click Theme in the toolbar.
• The grid view shows your themes. Click a tile to open the rich editor. Hover the play button to apply a theme to PROGRAM without editing. Hover ✕ to delete.
• + New Theme creates a custom one from a default template.
• Save — the theme persists in your library and can be applied or referenced by Looks.

Looks (Looks tab)

A Look is a named configuration of:

• Which layers render: slide, media, messages, announcements, bible, props
• Which theme each output uses: theme_overrides[screenId] = themeId
• Per-screen layer overrides (one screen shows media, another doesn't)
• Transition duration

Click Looks in the toolbar (between Theme and Stage). The per-Look grid:

Click Make Live to activate the Look. PROGRAM repaints within ~1 second.

Unified render pipeline

Settings → Screens & Display → Advanced → Unified render pipeline toggle (default off during burn-in).

• ON — the active Look drives every output. Edit a Look and audience repaints in real time. Per-screen overrides take effect.
• OFF — v1.3-style global theme behaviour. Looks store data but don't drive output.

After one full successful service with the flag on, leave it on. v2 flips the default.

ace · agentic cue experience

v1.5.3

5 · Outputs (Screen Configuration)

⌘+⇧+S opens Screen Configuration — the single source of truth for outputs. It replaced the v1.0–v1.2 dashboard NDI / Audience / Stage toggles.

Audience vs Stage

• Audience — what your congregation sees. Lyrics, backgrounds, scripture. Edge-to-edge.
• Stage — what the worship team or preacher sees. Confidence layout (current / next slide, timer, clock, sermon notes). Operator-aware chrome.

Multi-display

Both roles support multiple displays — 7 audience screens plus 3 stage screens at once if your rig has the displays. Each role's toggle drives all assigned displays in lockstep.

Display Mode toggle (per output)

• Borderless Fill (default) — preserves your operator menu bar, multi-display friendly. Used by most rigs.
• True Fullscreen — own Mission Control Space, smoother for single-output venues. Has its own Space; swipe with a four-finger trackpad.

State badges

Screens menu (macOS menu bar)

• Configure Screens ⌘+⇧+S
• Identify All Displays — pops DISPLAY N overlays on every connected display.
• Test Pattern submenu — Color Bars / Focus / Greyscale / Solid.
• Clear All Overlays Esc

ace · agentic cue experience

v1.5.3

6 · Detection — lyrics and Bible

ACE uses local Whisper (CoreML on Apple Silicon, ~200 ms latency) to transcribe, then matches transcripts to your imported library via FAISS vector search.

Modes

• Auto — detects either lyrics or Bible references; switches contextually.
• Song — locks to lyric matching (best during worship sets).
• Bible — locks to scripture references (best during sermon).

Sermon recording

Bottom-right Sermon Notes panel:

1. Optional — title and speaker.
2. Start Recording — backend captures full transcript, extracts key points, auto-detects Bible references.
3. Stop Recording — Export button appears. Export contains full transcript, key points and scripture, with the live-transcript snippet that triggered each scripture match shown beneath the canonical verse (e.g. ↳ heard: "God works all things for good" under Romans 8:28).
4. Past sermons listed under Settings → Data → Sermon History.

Smart Bible auto-advance v1.5.3

When a Bible verse is currently displayed, ACE listens for the next verse's text in the live transcript. If the preacher reads verse N+1 directly without saying "next verse," ACE auto-advances when the cosine-similarity match against verse N+1's text crosses ≥ 0.70.

Detection Reset v1.5.3

⌘+⇧+R clears stuck vote accumulators, transcript history, and rebuilds the Whisper context-prompt — without stopping audio capture.

ace · agentic cue experience

v1.5.3

7 · Stage layouts

The operator confidence monitor is fully designable. Stage tab in the toolbar.

Pick a preset (current-next, current-notes, current-timers, system-clock, blank) or + New Layout.

Object types

• Type — text (static label) · linked_text (live source) · shape (box) · image · media_placeholder
• Source (for linked_text) — current_slide, next_slide, system_clock, timer, presentation_name, stage_message, video_countdown
• Position / size — drag on canvas (1920×1080 logical).
• Style — pick a semantic token (stage.text.primary, stage.text.secondary, stage.text.next, stage.text.timer, stage.text.clock, stage.text.muted) or a custom hex.

When a token is picked the active theme drives the rendered color. Custom hex overrides per-object.

Mirror Program v1.5.3

Each stage layout has a Mirror Program checkbox in the editor topbar. When on, the stage screen mirrors whatever's on the audience output (slide image, scripture, song background, video) as a full-bleed backdrop, with the layout's text objects rendered on top. Speakers see exactly what the audience sees plus their confidence cues — without turning around.

The mirror reads from the global display theme (display_*) so it always tracks the live audience output, regardless of any per-screen Look override.

ace · agentic cue experience

v1.5.3

8 · Service Plan

Drag songs, scripture, prayer, announcements, sermon and media into a vertical timeline. Press Go On Air to advance through items.

• Planning Center Online sync available if PCO is configured. For now, reach the integrations panel via direct URL /settings?tab=integrations; v2 surfaces this in the main UI.
• Each item: assigned theme, layer config, timer, auto-advance rules.

9 · Quick Screens · ⌘+J

Floating panel — bottom-right of the dashboard. Type a message, pick a theme, push to PROGRAM in one click.

• ⌘+J toggles open / closed (skipped while focused inside an input or textarea so you can still type "j").
• ⌘+↵ displays.
• The last 10 entries are kept on the Recent shelf for one-click reuse.
• Use cases — announcements, prayer calls, offering reminders, lower-thirds.

ace · agentic cue experience

v1.5.3

10 · Settings

⌘+, or click ⚙ in the toolbar. Sidebar groups every setting under a high-level category.

General

• App — name, theme (light / dark — currently dark only), language.
• Updates — running version, latest release, update notes.
• Audio — input device, sample rate, gain, Recovery (Re-download speech model, Re-run setup wizard).
• Network — backend port, allowed origins, CORS.
• CCLI — your church CCLI license number; renders on slide footers for compliance.
• Display Hold — how long strong-confidence and weak matches stay on screen.
• Tour — re-trigger the in-app tour.

Detection

• Detection mode — Auto / Song-only / Bible-only.
• Confidence threshold — global AI confidence floor.
• Bible parser — strict / lenient match modes; verse-context window.
• Voice control — voice-command toggle (e.g. "ACE next slide").
• Whisper model — tiny / base / small / medium / large-v3 (memory ↔ accuracy trade-off).
• Transcription language — Auto-detect (bilingual) / English / Spanish / Portuguese / etc.
• Online transcription — Deepgram on / off.
• Auto-display Bible — toggle whether Bible detection auto-pushes to PROGRAM.
• Bible auto-display floor — confidence ≥ 0.60 threshold (v1.5.3, was 0.55).

Output

• Screens & Display — ⌘+⇧+S Configure Screens; per-output assignment, role, display mode.
• Theme background — bg_mode, bg_color, bg_gradient_*, bg_image_path, bg_image_opacity.
• Theme typography — font_family, font_size, font_weight, font_color, subtitle_color, position, h_margin, v_margin, line_reveal, reveal_speed, visible_lines, text_shadow + shadow color/offset.
• Unified render pipeline — opt-in flag for Look-driven rendering.
• ProPresenter — output via OSC bridge.
• ATEM — Blackmagic ATEM control.
• NDI — toggle, source name, channel.
• MIDI — incoming MIDI shortcut bindings.

Data

• Song Index — re-index, drop & rebuild FAISS, view index size.
• Import — default conflict-resolution mode, default theme.
• PowerPoint rendering — DPI (default 150), backend (LibreOffice headless).
• LibreOffice deferred-install — install / re-install / status.

Integrations (hidden by default)

Reach via direct URL /settings?tab=integrations. ACE handles core features without operator-supplied API keys; v2.0 will introduce a license gateway that proxies free-tier services and gates paid-tier ones behind subscription — no keys, ever.

• ACRCloud · Anthropic · Deepgram · Genius · Pixabay · Planning Center Online.

ace · agentic cue experience

v1.5.3

11 · Keyboard shortcuts

The canonical shortcut catalog lives in src/lib/shortcuts.ts. This section mirrors it.

// Rebind "Reset Detection" from ⌘⇧R to ⌘⇧Y
const cur = JSON.parse(localStorage.getItem("ws-shortcuts-v1") || "{}");
cur["detection-reset"] = { key: "y", meta: true, shift: true };
localStorage.setItem("ws-shortcuts-v1", JSON.stringify(cur));
window.dispatchEvent(new CustomEvent("ws-shortcuts-updated"));

To restore one shortcut to default — delete its key. To reset every shortcut — localStorage.removeItem("ws-shortcuts-v1").

Clear layers

Slide playback

Screen outputs

Navigation

Toolbar modes

Detection

macOS menu (always works)

Quick Screens (when panel is open)

ace · agentic cue experience

v1.5.3

12 · Common workflows

Sunday-morning worship service

1. Open ACE 30 minutes before service.
2. Service Plan tab — drag today's songs in order (or sync from Planning Center).
3. ⌘+⇧+S — confirm Audience and Stage toggles are on, displays assigned, both Live.
4. Pick the active Look that matches the service mood (e.g. "Standard" / "Worship" / "Scripture").
5. Start detection. Walk to the booth, hand over to the operator.
6. During worship — ACE auto-advances through detected songs. Operator presses F1 between songs to clear, or just lets the Display Hold expire.
7. Sermon — switch to Bible mode (⌃+B) or stay on Auto. Sermon Notes start recording; scripture detected and pushed automatically.
8. After service — stop detection, Export Last Sermon for archiving.

Mid-week conference / lecture

1. Import the speaker's deck (PPTX / Keynote / PDF) via the wizard.
2. Bible references in slide titles and notes are auto-tagged.
3. During the talk — slides advance automatically as the speaker progresses. → for manual override.

Theater / live show

1. Pre-load cue order in Service Plan.
2. Use Quick Screens (⌘+J) for ad-hoc announcements between scenes.
3. Lower-third overlays via the props layer (foreground media in Media Bin).

ace · agentic cue experience

v1.5.3

13 · Troubleshooting

Mic level low (visualizer is amber)

• Check the input device in Settings → General → Audio.
• If using an external interface — confirm the worship-room mic is routed to ACE's input.
• Move closer to the mic source if possible.

Detection isn't picking up my song

• Confirm it's imported — Settings → Data → Song Index.
• Try Manual Search (⌘+F) — confirms FAISS has the lyrics indexed.
• If genuinely obscure, ACE falls back to ACR audio fingerprinting (if you've configured an ACR key).

Slide doesn't reach the audience output

• Confirm Audience output is Live (green badge in ⌘+⇧+S).
• If the active Look has the media layer disabled per-screen, slides hide. Check the Looks panel.

Stage output shows wrong layout

• Stage tab — confirm the right preset is active.
• Or /api/stage/layouts/active returns the wrong id — check Settings → Output → Stage.

Detection got stuck on verse 1 / chorus and won't advance

• This was the v1.3 bug fixed in v1.4. Confirm Settings → Updates shows v1.4 or later.

Detection is hallucinating / pushing the wrong verse

• Press ⌘+⇧+R to clear stuck votes, transcript history, and rebuild the Whisper context-prompt without stopping audio capture.
• If it persists — switch detection mode (Auto / Song / Bible). The mode-switch handler runs the same reset automatically.

PPTX imports as just text on a black background, no slide design

• LibreOffice headless conversion failed. Most common causes — profile lock (another LO instance open), missing JRE, sandbox permission denial.
• v1.5.3 isolates each import to its own profile dir + adds --nolockcheck, killing the most common case. If it still happens, the backend log prints captured stdout / stderr from soffice — paste that to support.

Mirror Program toggle saved but stage screen didn't change

• Fixed in v1.5.3. If you're on v1.5.2 or earlier, the workaround is — switch to the Blank layout, save, switch back, save.

Old slide keeps showing after I deleted the PPTX

• Fixed in v1.5.3 — delete now clears display_bg_image_path if it pointed at one of the removed slides, plus the audience window cache-busts on path change. On earlier versions — F2 (Clear Slide) or ⌘+⇧+B (Black) clears the stuck image manually.

Imported the same-named PPTX twice and the audience screen shows the old version

• Fixed in v1.5.3 (per-path cache-bust on slide URL). On earlier versions — hard-reload the audience window (⌘+⇧+R inside the audience window if accessible) or restart the app.

ace · agentic cue experience

v1.5.3

14 · Where things live

15 · Glossary

16 · Feature index

Every distinct surface in the app. Use it as a discovery aid — the workflow narrative is in earlier sections.

Toolbar (top of dashboard)

Sidebar (left)

• Library tabs — Songs / Presentations / Bibles.
• Sub-filters — recently used, by source, by language.
• Drag-reorder — sets the current Service Plan order.
• Add via + — opens AddSongModal (Genius / paste lyrics / search).
• Drag-drop — accepts files, routes through the Import wizard.

Centre column (depends on tab)

Right panel

• Preview / Program tabs — what's queued (Preview) and what's live (Program).
• Macros — operator-fired automation buttons.
• Sermon Notes — title, speaker, Start / Stop Recording. Auto-detects scripture during sermons and extracts key points.

Media Bin (bottom dock)

• Playlists — saved sets of media (e.g. "Christmas backgrounds").
• Asset library — all imported videos / images, filterable.
• Stock Bin filter — Pixabay search (if configured).
• Per-asset fit mode — fit / fill / stretch.
• Drag onto preview — sets as audience background.

Output windows

• Audience window (/stage?role=program) — renders Program theme + slide / scripture / lyrics overlays. Cold-start clears stale bg_image_path (v1.5.3). Slide URL cache-busts on path change. Slide aspect objectFit: "cover" (full-bleed).
• Stage window (/stage?role=stage) — renders the active stage layout's objects. Honours per-screen Look theme override. Mirror Program (v1.5.3) — full-bleed audience backdrop with stage cues on top.
• Multi-view (/multiview) — live preview of every output in one window. Read-only.

Floating surfaces

• Quick Screens (⌘+J) — bottom-right floating panel.
• Command Palette (⌘+K) — fuzzy-search action launcher.
• In-app tour — re-trigger from Settings → General → Show tour again.
• Onboarding wizard — Welcome → Backend → Model → Permissions → Done. Re-run from Settings → Audio → Recovery.

17 · API endpoints

Backend runs on http://127.0.0.1:8765 by default. Highlights below; full list in docs/API.md.

WebSocket events

ws://127.0.0.1:8765/ws — broadcast channel. Notable types — detection, bible_detection, auto_display, display_cleared, media_cleared, blackout, theme_applied, look_changed, stage_layout_changed, media_foreground_set, media_foreground_cleared, slides_imported, libreoffice_install_progress, sermon_note, voice_command.