# Curtain Call Instructions

## Contents

- [Curtain Call Instructions](#curtain-call-instructions)
  - [Contents](#contents)
  - [Overview and Interface](#overview-and-interface)
    - [Page Layout](#page-layout)
    - [Cue Table and Playback](#cue-table-and-playback)
    - [Fullscreen, Status, and Logs](#fullscreen-status-and-logs)
  - [Keyboard Shortcuts](#keyboard-shortcuts)
  - [Show Configuration](#show-configuration)
    - [Application Options](#application-options)
    - [Show Metadata](#show-metadata)
    - [Cue Definition](#cue-definition)
    - [Cue Fields](#cue-fields)
  - [Startup and Offline Use](#startup-and-offline-use)
  - [Venue Notes](#venue-notes)
  - [Use, Sharing, and Responsibility](#use-sharing-and-responsibility)
    - [Project Code](#project-code)
    - [Demo Audio](#demo-audio)
    - [Disclaimer](#disclaimer)

## Overview and Interface

Curtain Call is a browser-based controller for a show's audio cues. The cue table lists each cue and its scene notes, and provides playback, volume, fade, sequencing, and status controls.

### Page Layout

- The sticky top header shows the show name and version, global status, elapsed show timer, current clock time, project name/version, log export, and the instructions link.
- The cue table columns, in order, are ID, HK, FLAGS, Scene, Cue In, Cue Out, Audio Control, MUTE, volume decrease, current VOL, AMV, volume increase to target, volume boost, F.IN, F.OUT, fade-stop, PC, ECA, and CD.
- The cue and console log panes are fixed at the bottom of the page, left of the main control panel in the bottom-right corner. The panel has a large green GO button, which starts the next cue in the list (the cue after the last one started, same as Spacebar when nothing is playing), plus a master stereo position slider (L to R, step 5%, C centers it; it moves all cues together and does not change volumes), and LOCK, MUTE, and STOP. The cue table reserves bottom space so its rows can scroll above them.

### Cue Table and Playback

- Each row represents one cue and shows its number, hotkey, scene name, cue-in and cue-out notes, audio player, current volume, target volume, fade times, play count, end action, and delay.
- The down-arrow-to-bar symbol in the FLAGS column marks a cue that lowers other cues while it plays. Select it to inspect that cue's ducking settings.
- Use the browser audio controls to play, pause, or seek within a cue. Pausing fires the app's pause handler and may trigger that cue's configured end action; seeking is treated separately.
- Scene and cue-in/cue-out text is shortened in the table after 100 characters.
- The current volume is displayed as a percentage. AMV is the configured target volume.
- Use - and + to change volume in 5 percent steps. + stops at the configured target.
- Use the boost control (⨁) to raise volume above the target, up to 150 percent.
- Each cue's MUTE button silences only that cue. UNMUTE restores it without changing its volume setting, fade, or playback position. Its state is included in exported session logs.
- MUTE silences all cues without pausing playback or changing cue volumes. Press UNMUTE to restore sound. Mute is independent of STOP, which stops and resets the show.
- Audio ducking lowers a configured target cue while its source cue is playing, then restores it over the configured release time when the source pauses, stops, ends, or fails. If several sources duck the same cue, the strongest active attenuation applies.
- F.IN and F.OUT show the configured fade-in and fade-out durations in seconds.
- The fade-out/next control (⏭) fades and stops the current cue. Automatic advancement depends on the cue's end action and delay, subject to the negative-delay behavior described below.
- PC is the configured play count. ECA means End Cue Action; `playNext` is the supported automatic action. CD is the cue delay.

### Fullscreen, Status, and Logs

- Click the Current Time cell to enter or leave fullscreen. The app does not bind F11; use the browser or operating system fullscreen shortcut if available.
- Green indicates playing, yellow indicates fading, gray indicates elapsed or stopped, red indicates an audio error, and blue indicates loading.
- Monitor the on-screen cue and console logs for status and error messages. The export control downloads a session report with app/show metadata, each cue's configured and runtime state, and the full cue and console entries with severity labels.

## Keyboard Shortcuts

- Number keys 1-9 play cues 1-9. The 0 key maps to cue 0, which does not exist in this show, so it has no effect; use a configured hotkey for cue 10 or later. Press a cue's matching number again while it is playing to fade and stop it.
- A cue's configured `hotKey` also toggles that cue between play and fade-stop. Matching is case-insensitive.
- If all cue hotkeys are blank, the app assigns keys in order from its built-in character list: `qwertyuiopasdfghjklçzxcvbnm`. If any cue has a hotkey set, the app does not fill the remaining blank values. Duplicate assignments are not checked, and cues beyond the list's 27 keys have no automatically assigned hotkey.
- In the active demo show, every cue has a fixed `hotKey`: A and P for the pre-show cues, O for the overture, M/G/L/S/D/N/W/F for the act scenes, and X for the exit music. Automatic assignment only happens when every cue's hotkey is blank.
- Spacebar fades and stops the first cue currently playing. If none is playing, it starts the cue after the last cue started, if one remains.
- F1 opens these instructions in a separate tab.
- Use LOCK before stepping away to disable the app controls and cue hotkeys. Audio already playing continues. Use Unlock Controls to resume operation. The lock is an accidental-interaction guard, not password protection. Escape remains an immediate emergency stop; the lock-screen emergency-stop button asks for confirmation.
- The master mute state is included in exported session logs.
- Escape or the visible STOP button stops all cues, returns playback to the beginning, restores configured play counts and delays, and resets the show timer. This action cancels Curtain Call's pending timers and does not clear timers belonging to the rest of the page.

## Show Configuration

Edit `audio-files/audio-show.js` to change show metadata and cue definitions. Put active audio assets in `audio-files/`. The filename, extension, and letter case in `fileName` must match the actual file.

### Application Options

```js
var curtainCallOptions = {
    highContrast: false,
    autoCollapsePlayedGroups: false
};
```

These options live in `audio-files/audio-show.js`. Set `highContrast` to `true` for a stronger contrast palette; keyboard focus indicators remain visible regardless of this setting. Set `autoCollapsePlayedGroups` to `true` to collapse a cue group automatically once every cue in it has played to its end (a cue stopped early with fade-out or pause does not count; a looping cue counts once the operator stops it). A collapsed group expands again when one of its cues restarts; STOP/Escape expands all groups. It is off by default.

Ducking is configured on each source cue, not in `curtainCallOptions`. A cue without `audioDucking`, or with an empty `targetCues` list, controls no other cues. Give every cue a unique lowercase `id` immediately after its filename. The cue containing `audioDucking` is the source; list target cue IDs, not row numbers. Set `targetCues` to `"all"` or `"*"` to affect every other cue; the source cue is never included. For example, the phone-warning cue can lower the ambience cue:

```js
audioDucking: {
    targetCues: ["ambience"],
    attenuation: 0.75,
    releaseDuration: 1.5
}
```

To duck several cues from one source, list each target ID in the same array:

```js
audioDucking: {
    targetCues: ["ambience", "scene-1", "scene-4"],
    attenuation: 0.75,
    releaseDuration: 1.5
}
```

`attenuation` is each target's gain multiplier, greater than 0 and at most 1; `0.75` means 75% of normal signal. `releaseDuration` is the number of seconds each target takes to return after the source stops; use `0` for an immediate return. These two settings apply to all target IDs listed in the rule. When multiple sources target the same cue, the strongest active attenuation applies. Ducking uses a separate gain stage and does not alter the target cue's configured volume, fades, or mute setting.

### Show Metadata

```js
var audioShow = {
    name: "Show title",
    version: "Cue-set version",
    updated: "YYYY-MM-DD"
};
```

- `name` identifies the show; use a clear title.
- `version` identifies the version of the show's cue set. Choose a numbering scheme that suits the production.
- `updated` records when the cue set was last changed. Use an unambiguous date format, such as YYYY-MM-DD or DD-MM-YYYY.

The active demo values are `name: "The Lighthouse Keeper (Demo)"`, `version: "Demo Theatre, Main Stage"`, and `updated: "15.10.2026"`.

### Cue Definition

```js
var audioCues = [
    {
        fileName: "ambience.mp3",
        id: "ambience",
        volume: 70,
        fadeInDuration: 2,
        fadeOutDuration: 3,
        sceneName: "Opening",
        cueIn: "Start on the stage manager's cue.",
        cueOut: "Stop after the scene change.",
        playCount: 1,
        nextCue: "playNext",
        cueDelay: 0,
        hotKey: "q",
        crossfadeDuration: 0,
        audioDucking: {
            targetCues: []
        }
    }
];
```

### Cue Fields

- `fileName`: audio filename, including its extension, stored in `audio-files/`. Confirm that the referenced file exists and spelling/capitalization match.
- `id`: unique, lowercase cue identifier placed after `fileName`. Use letters, numbers, and hyphens, starting with a letter. Ducking targets refer to this ID, so it stays meaningful if cues are reordered.
- `volume`: target volume as a percentage; 0 is silent and 100 is the usual maximum target. The boost control can raise playback above that target.
- `fadeInDuration`: seconds for the cue to ramp from silence to its target volume.
- `fadeOutDuration`: seconds for the cue to ramp from its current volume to silence.
- `crossfadeDuration`: optional overlap time in seconds between repeated iterations of this cue. Set it on this cue in `audio-show.js`; omit it or use 0 to disable. It only applies when `playCount` is greater than 1 or `"loop"`, and must be less than half the audio's duration. If the track is too short or the next iteration is not ready, playback falls back to the normal repeat fade. The normal fade-out still applies to the final iteration.
- For a consistent show definition, include both `crossfadeDuration` and `audioDucking` on every cue. Use `crossfadeDuration: 0` and `audioDucking: { targetCues: [] }` when those features are unused.
- `sceneName`: concise scene or cue label. Consistent, descriptive names make the cue list easier to scan.
- `group`: optional act or scene group name, e.g. `"Act 1"`. Cues sharing the same name get the same muted row background; colors come from `curtainCall.groupColors` in `app.js`, assigned in order of first appearance and reused if there are more groups than colors. Omit or leave blank for no background. Group colors are not shown in high-contrast mode. Each run of consecutive cues with the same group gets a header row; select it to collapse or expand those cues. Collapsed cues stay loaded and can still be played by hotkey or sequencing, so check that nothing is playing before hiding a group. Collapse state is not saved across reloads.
- `cueIn`: optional notes about when or how to start the cue, including script lines, timing, effects, or coordinated stage actions.
- `cueOut`: optional notes about when or how to end the cue, including fade timing, script lines, or coordinated actions.
- `playCount`: a positive number of plays or the string `loop` for continuous looping until stopped.
- `nextCue`: use `playNext` to advance automatically to the following cue; leave blank to stop normal automatic progression after this cue.
- `cueDelay`: numeric delay associated with cue progression. For non-negative values, normal automatic progression requires `nextCue: "playNext"` and the last play; the next cue is scheduled after `cueDelay` seconds, and the CD cell counts down while it waits, then shows the configured value again. A negative value starts the following audio near the end of the current cue when its play count is at most one. This negative-delay path can start the next cue even if `nextCue` is blank. It creates overlap, not an automatic crossfade. Use 0 for no configured delay.
- `hotKey`: optional character to play or fade-stop this cue. Choose keys that are easy to remember and unique; uniqueness and conflicts with other shortcuts are not checked. Automatic assignment only happens if every cue's hotkey is blank; partial blank assignments stay blank.
- `audioDucking`: optional settings owned by the source cue. Omit it or set `targetCues: []` for no targets. When targets are listed, use their cue IDs and provide an `attenuation` multiplier and `releaseDuration` in seconds.

The active file defines 12 cues in playback order, grouped as Pre-show (House Ambience, Phones Announcement), Act 1 (Overture, scenes 1.1-1.3), Act 2 (scenes 2.1-2.3), Act 3 (Dawn, Finale), and Post-show (Exit Music). It demonstrates looping cues, a two-play cue, 5-second iteration crossfades, `playNext` chaining with delays, a negative `cueDelay` overlap (Dawn into Finale), fixed hotkeys, and cue groups. The phones announcement ducks `house-ambience` to 25% with a 4-second release; Storm Warning ducks all other cues to 20% with a 3-second release.

## Startup and Offline Use

1. Serve the project over HTTP or HTTPS for playback. On Linux, run `./run-local.sh`; if Python 3 is missing, it asks before offering installation through the system package manager. On Windows, double-click `run-local.bat`; it uses PowerShell and does not require Python. Both select an available localhost port and open Curtain Call in your browser. Press Ctrl+C in the server window to stop it. A `file://` page may show audio metadata but the browser can reject playback; service-worker and reachability checks are also unavailable there.
2. The app validates show metadata and cue fields before rendering controls. Invalid configuration is reported by field in the Console Log, cue controls are withheld, and playback shortcuts are disabled.
3. After configuration passes over HTTP/HTTPS, the file check reports `FILES REACHABLE` or `FILES UNAVAILABLE`. It uses HTTP HEAD requests to confirm cue-file reachability; it does not verify that files decode or have been cached for offline use. On `file://`, the check is skipped because browsers block fetch-based HEAD checks from local-file pages.
4. The service worker precaches core app files and caches audio when it is fetched. To prepare for offline playback, load each required cue while online, then test the show offline before performance.

## Venue Notes

Follow the theatre staff and venue's current house rules. The demo show includes an opening cue about silencing phones and other sound-emitting devices. Confirm the venue's recording policy; these are venue rules, not settings enforced by Curtain Call.

## Use, Sharing, and Responsibility

### Project Code

You may use and modify the Curtain Call code. If you change the code, share the modified source and credit the original Curtain Call project and its creator. Keep this notice with copies you redistribute. These terms apply to Curtain Call code and do not replace or change licenses for third-party material.

### Demo Audio

The demo audio is provided for demonstration and evaluation. The audio notice in `audio-files-full/READ ME` states that it may be used, modified, and shared, including commercially, under Creative Commons Attribution 4.0 International (CC BY 4.0), provided the license terms are followed. Credit the original creators by name and include any attribution information they request. Check individual files for separate rights or attribution details; these terms cannot grant rights the project does not hold.

### Disclaimer

> The code and demo audio are provided as-is, without warranties. To the fullest extent permitted by applicable law, the creator accepts no responsibility or liability for claims, losses, or damages arising from their use. You are responsible for checking applicable laws, third-party terms, and any permissions needed for your use.
