From 1b3ff1e78cd05b069e723d59eb55b2aed0207848 Mon Sep 17 00:00:00 2001 From: jenstandstad Date: Tue, 18 Aug 2026 21:02:16 +0200 Subject: [PATCH] Add per-node scene music volume control Author a music track and volume (0-100%) per story node; the runtime scales it to 0-1 and applies it without restarting the track when only the level changes. Adds migration 024, threads music_volume through the repository/runtime, and gives the node inspector a volume slider. Co-Authored-By: Claude Opus 4.8 --- migrations/024_story_node_music_volume.sql | 4 ++++ server/migrations.integration.test.ts | 6 +++--- server/narrativeRepository.ts | 13 +++++++------ server/storyGraphRepository.ts | 11 ++++++----- src/App.tsx | 2 +- src/audio.ts | 13 ++++++++----- src/mysteryGraph.tsx | 7 ++++++- src/narrative.tsx | 2 +- 8 files changed, 36 insertions(+), 22 deletions(-) create mode 100644 migrations/024_story_node_music_volume.sql diff --git a/migrations/024_story_node_music_volume.sql b/migrations/024_story_node_music_volume.sql new file mode 100644 index 0000000..6d42499 --- /dev/null +++ b/migrations/024_story_node_music_volume.sql @@ -0,0 +1,4 @@ +-- Per-node scene-music volume (0-100%). Applied whenever a node sets a track; +-- selecting the same track on a later node with a different volume just adjusts +-- the level without restarting the music. +ALTER TABLE osint.story_nodes ADD COLUMN music_volume SMALLINT NOT NULL DEFAULT 100 CHECK (music_volume BETWEEN 0 AND 100); diff --git a/server/migrations.integration.test.ts b/server/migrations.integration.test.ts index e677182..2b548bc 100644 --- a/server/migrations.integration.test.ts +++ b/server/migrations.integration.test.ts @@ -33,7 +33,7 @@ suite('PostgreSQL migrations', () => { const migrationsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'migrations') const firstRun: string[] = [] await runMigrations(testDatabaseUrl, migrationsDir, message => firstRun.push(message)) - expect(firstRun.filter(message => message.startsWith('apply '))).toHaveLength(23) + expect(firstRun.filter(message => message.startsWith('apply '))).toHaveLength(24) const client = new Client({ connectionString: testDatabaseUrl }) await client.connect() @@ -49,7 +49,7 @@ suite('PostgreSQL migrations', () => { ])) expect(tableNames).not.toEqual(expect.arrayContaining(['cases', 'widgets', 'widget_relations', 'cutscenes', 'dialogue_steps', 'mystery_chapters', 'seen_dialogue'])) const ledger = await client.query<{ count: string }>('SELECT COUNT(*)::text AS count FROM osint.schema_migrations') - expect(ledger.rows[0].count).toBe('23') + expect(ledger.rows[0].count).toBe('24') const connectionColumns = await client.query<{ column_name: string }>(`SELECT column_name FROM information_schema.columns WHERE table_schema='osint' AND table_name='exhibit_connections'`) expect(connectionColumns.rows.map(row => row.column_name)).toEqual(expect.arrayContaining(['label', 'tightness', 'tag_style', 'tag_position_percent', 'tag_lateral_offset'])) const eventOccurrence = await client.query<{ is_nullable: string }>(`SELECT is_nullable FROM information_schema.columns WHERE table_schema='osint' AND table_name='event_exhibits' AND column_name='occurred_at'`) @@ -58,7 +58,7 @@ suite('PostgreSQL migrations', () => { const secondRun: string[] = [] await runMigrations(testDatabaseUrl, migrationsDir, message => secondRun.push(message)) - expect(secondRun.filter(message => message.startsWith('skip '))).toHaveLength(23) + expect(secondRun.filter(message => message.startsWith('skip '))).toHaveLength(24) expect(secondRun.some(message => message.startsWith('apply '))).toBe(false) }) }) diff --git a/server/narrativeRepository.ts b/server/narrativeRepository.ts index 96c3533..a110509 100644 --- a/server/narrativeRepository.ts +++ b/server/narrativeRepository.ts @@ -16,7 +16,7 @@ export type RuntimeUtterance = { } export type RuntimeNode = { id: string; kind: 'cutscene' | 'dialogue' | 'level'; label: string - componentKey?: string | null; levelSlug?: string | null; musicUrl?: string | null + componentKey?: string | null; levelSlug?: string | null; musicUrl?: string | null; musicVolume?: number utterances?: RuntimeUtterance[]; rootId?: string | null } export type PlaythroughState = { playthrough: PlaythroughSummary; node: RuntimeNode | null } @@ -60,7 +60,7 @@ export interface NarrativeRepository { deletePose(npcId: string, poseKey: string): Promise } -type GraphNodeRow = { id: string; node_type: string; label: string; component_key: string | null; level_template_version_id: string | null; music_asset_id: string | null } +type GraphNodeRow = { id: string; node_type: string; label: string; component_key: string | null; level_template_version_id: string | null; music_asset_id: string | null; music_volume: number } export function createNarrativeRepository(pool: Pool, objectStorage: ObjectStorage): NarrativeRepository { // ---- Runtime: walking the story graph ------------------------------------- @@ -97,12 +97,13 @@ export function createNarrativeRepository(pool: Pool, objectStorage: ObjectStora } async function resolveNodeForPlay(nodeId: string, levelSlug: string | null): Promise { - const node = (await pool.query('SELECT id,node_type,label,component_key,level_template_version_id,music_asset_id FROM osint.story_nodes WHERE id=$1', [nodeId])).rows[0] + const node = (await pool.query('SELECT id,node_type,label,component_key,level_template_version_id,music_asset_id,music_volume FROM osint.story_nodes WHERE id=$1', [nodeId])).rows[0] if (!node) return null const musicUrl = node.music_asset_id ? `/api/assets/${node.music_asset_id}` : null - if (node.node_type === 'cutscene') return { id: node.id, kind: 'cutscene', label: node.label, componentKey: node.component_key, musicUrl } - if (node.node_type === 'level') return { id: node.id, kind: 'level', label: node.label, levelSlug, musicUrl } - if (node.node_type === 'dialogue') return { id: node.id, kind: 'dialogue', label: node.label, musicUrl, ...(await resolveDialogueGraph(node.id)) } + const musicVolume = node.music_volume / 100 + if (node.node_type === 'cutscene') return { id: node.id, kind: 'cutscene', label: node.label, componentKey: node.component_key, musicUrl, musicVolume } + if (node.node_type === 'level') return { id: node.id, kind: 'level', label: node.label, levelSlug, musicUrl, musicVolume } + if (node.node_type === 'dialogue') return { id: node.id, kind: 'dialogue', label: node.label, musicUrl, musicVolume, ...(await resolveDialogueGraph(node.id)) } return null // gates are auto-resolved during advance and never surfaced } diff --git a/server/storyGraphRepository.ts b/server/storyGraphRepository.ts index 9603b79..9c3d4f7 100644 --- a/server/storyGraphRepository.ts +++ b/server/storyGraphRepository.ts @@ -13,7 +13,7 @@ export type StoryNodeType = 'cutscene' | 'dialogue' | 'level' | 'det_gate' | 'll export type TerminalDto = { id: string; terminalKey: string; label: string; toNodeId: string | null; sortOrder: number } export type StoryNodeDto = { id: string; nodeType: StoryNodeType; label: string; hasUtterances: boolean - xpos: number; ypos: number; levelTemplateVersionId: string | null; componentKey: string | null; musicAssetId: string | null + xpos: number; ypos: number; levelTemplateVersionId: string | null; componentKey: string | null; musicAssetId: string | null; musicVolume: number terminals: TerminalDto[] } export type StoryGraphDto = { mysteryId: string; entryNodeId: string | null; nodes: StoryNodeDto[] } @@ -37,7 +37,7 @@ const DEFAULT_TERMINALS: Record export interface StoryGraphRepository { getGraph(mysteryId: string): Promise createNode(mysteryId: string, input: { nodeType: StoryNodeType; xpos: number; ypos: number; label?: string }): Promise - updateNode(nodeId: string, input: Partial<{ label: string; xpos: number; ypos: number; hasUtterances: boolean; componentKey: string | null; levelTemplateVersionId: string | null; musicAssetId: string | null }>): Promise + updateNode(nodeId: string, input: Partial<{ label: string; xpos: number; ypos: number; hasUtterances: boolean; componentKey: string | null; levelTemplateVersionId: string | null; musicAssetId: string | null; musicVolume: number }>): Promise deleteNode(nodeId: string): Promise addTerminal(nodeId: string, input: { terminalKey: string; label?: string }): Promise updateTerminal(terminalId: string, input: Partial<{ label: string; sortOrder: number; toNodeId: string | null }>): Promise<{ ok: boolean; error?: string }> @@ -61,8 +61,8 @@ export function createStoryGraphRepository(pool: Pool): StoryGraphRepository { const mystery = await pool.query<{ id: string; entry_node_id: string | null }>('SELECT id,entry_node_id FROM osint.mysteries WHERE id=$1', [mysteryId]) if (!mystery.rows[0]) return null const [nodes, terminals] = await Promise.all([ - pool.query<{ id: string; node_type: StoryNodeType; label: string; has_utterances: boolean; xpos: number; ypos: number; level_template_version_id: string | null; component_key: string | null; music_asset_id: string | null }>( - 'SELECT id,node_type,label,has_utterances,xpos,ypos,level_template_version_id,component_key,music_asset_id FROM osint.story_nodes WHERE mystery_id=$1 ORDER BY created_at', [mysteryId]), + pool.query<{ id: string; node_type: StoryNodeType; label: string; has_utterances: boolean; xpos: number; ypos: number; level_template_version_id: string | null; component_key: string | null; music_asset_id: string | null; music_volume: number }>( + 'SELECT id,node_type,label,has_utterances,xpos,ypos,level_template_version_id,component_key,music_asset_id,music_volume FROM osint.story_nodes WHERE mystery_id=$1 ORDER BY created_at', [mysteryId]), pool.query<{ id: string; parent_node_id: string; terminal_key: string; label: string; to_node_id: string | null; sort_order: number }>( `SELECT t.id,t.parent_node_id,t.terminal_key,t.label,t.to_node_id,t.sort_order FROM osint.story_node_terminals t JOIN osint.story_nodes n ON n.id=t.parent_node_id WHERE n.mystery_id=$1 ORDER BY t.sort_order,t.terminal_key`, [mysteryId]), @@ -77,7 +77,7 @@ export function createStoryGraphRepository(pool: Pool): StoryGraphRepository { mysteryId, entryNodeId: mystery.rows[0].entry_node_id, nodes: nodes.rows.map(row => ({ id: row.id, nodeType: row.node_type, label: row.label, hasUtterances: row.has_utterances, - xpos: row.xpos, ypos: row.ypos, levelTemplateVersionId: row.level_template_version_id, componentKey: row.component_key, musicAssetId: row.music_asset_id, + xpos: row.xpos, ypos: row.ypos, levelTemplateVersionId: row.level_template_version_id, componentKey: row.component_key, musicAssetId: row.music_asset_id, musicVolume: row.music_volume, terminals: byNode.get(row.id) || [], })), } @@ -118,6 +118,7 @@ export function createStoryGraphRepository(pool: Pool): StoryGraphRepository { if (input.componentKey !== undefined) set('component_key', input.componentKey || null) if (input.levelTemplateVersionId !== undefined) set('level_template_version_id', input.levelTemplateVersionId || null) if (input.musicAssetId !== undefined) set('music_asset_id', input.musicAssetId || null) + if (input.musicVolume !== undefined) set('music_volume', Math.max(0, Math.min(100, Math.round(input.musicVolume)))) if (sets.length) await pool.query(`UPDATE osint.story_nodes SET ${sets.join(',')} WHERE id=$1`, values) const graph = await loadGraph(mysteryId) return graph?.nodes.find(node => node.id === nodeId) ?? null diff --git a/src/App.tsx b/src/App.tsx index 3ce944c..8923329 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -155,7 +155,7 @@ export function App() { // Scene music follows the current node (null inherits; a finished playthrough stops). useEffect(() => { - if (runtimeNode?.musicUrl) audio.setMusic(runtimeNode.musicUrl) + if (runtimeNode?.musicUrl) audio.setMusic(runtimeNode.musicUrl, runtimeNode.musicVolume) else if (playthrough?.status === 'finished') audio.setMusic(null) }, [runtimeNode, playthrough]) diff --git a/src/audio.ts b/src/audio.ts index 03a86d9..2663f1a 100644 --- a/src/audio.ts +++ b/src/audio.ts @@ -2,7 +2,7 @@ // SFX. Zero dependencies. Browsers block autoplay until a user gesture, so music/SFX // are primed on the first pointer interaction. type Sfx = 'advance' | 'choice' | 'sting' -const MUSIC_VOLUME = 0.5 +let baseVolume = 0.5 // authored scene volume (0-1); mute overrides to 0 let ctx: AudioContext | null = null function audioContext() { @@ -43,13 +43,16 @@ function fade(target: number, done?: () => void) { function startMusic() { if (!music || !currentUrl || muted) return const promise = music.play() - if (promise) promise.then(() => { pending = false; fade(MUSIC_VOLUME) }).catch(() => { pending = true }) + if (promise) promise.then(() => { pending = false; fade(baseVolume) }).catch(() => { pending = true }) } export const audio = { // A null url inherits whatever is already playing; a new url crossfades to it. - setMusic(url: string | null) { - if (!music || url === currentUrl) return + // The same url with a new volume just adjusts the level (no restart). + setMusic(url: string | null, volume?: number) { + if (!music) return + if (volume !== undefined) baseVolume = Math.max(0, Math.min(1, volume)) + if (url === currentUrl) { if (volume !== undefined && currentUrl && !muted) fade(baseVolume); return } currentUrl = url if (!url) { fade(0, () => music.pause()); pending = false; return } music.src = url @@ -59,7 +62,7 @@ export const audio = { toggleMute() { muted = !muted if (muted) fade(0) - else if (currentUrl) startMusic() + else if (currentUrl) { if (music && music.paused) startMusic(); else fade(baseVolume) } return muted }, isMuted() { return muted }, diff --git a/src/mysteryGraph.tsx b/src/mysteryGraph.tsx index 73334c0..9f765ad 100644 --- a/src/mysteryGraph.tsx +++ b/src/mysteryGraph.tsx @@ -4,7 +4,7 @@ import { CUTSCENE_COMPONENT_KEYS, DialoguePreview } from './narrative' type StoryNodeType = 'cutscene' | 'dialogue' | 'level' | 'det_gate' | 'llm_gate' type Terminal = { id: string; terminalKey: string; label: string; toNodeId: string | null; sortOrder: number } -type StoryNode = { id: string; nodeType: StoryNodeType; label: string; hasUtterances: boolean; xpos: number; ypos: number; levelTemplateVersionId: string | null; componentKey: string | null; musicAssetId: string | null; terminals: Terminal[] } +type StoryNode = { id: string; nodeType: StoryNodeType; label: string; hasUtterances: boolean; xpos: number; ypos: number; levelTemplateVersionId: string | null; componentKey: string | null; musicAssetId: string | null; musicVolume: number; terminals: Terminal[] } type AudioAsset = { id: string; originalName: string; mimeType: string } type Graph = { mysteryId: string; entryNodeId: string | null; nodes: StoryNode[] } type LevelTemplate = { versionId: string; slug: string; name: string; version: number } @@ -182,6 +182,7 @@ function NodeInspector({ node, graph, templates, audioAssets, onPatch, onSetEntr }) { const [label, setLabel] = useState(node.label) const [componentKey, setComponentKey] = useState(node.componentKey || '') + const [volume, setVolume] = useState(node.musicVolume) const nodeName = (id: string | null) => id ? (graph.nodes.find(n => n.id === id)?.label || '—') : '— unwired —' const usesComponent = node.nodeType === 'cutscene' || node.nodeType === 'det_gate' || node.nodeType === 'llm_gate' return
@@ -204,6 +205,10 @@ function NodeInspector({ node, graph, templates, audioAssets, onPatch, onSetEntr {audioAssets.map(asset => )} + {node.musicAssetId && }
Output terminals
{node.terminals.map(t =>
diff --git a/src/narrative.tsx b/src/narrative.tsx index 9b4a33f..86dafa1 100644 --- a/src/narrative.tsx +++ b/src/narrative.tsx @@ -2,7 +2,7 @@ import { useEffect, useMemo, useRef, useState, type FC } from 'react' import { audio } from './audio' export type RuntimeUtterance = { id: string; utterer: 'npc' | 'player'; speaker: { name: string; role: string }; poseUrl: string | null; text: string; childIds: string[]; terminalKey: string | null } -export type RuntimeNode = { id: string; kind: 'cutscene' | 'dialogue' | 'level'; label: string; componentKey?: string | null; levelSlug?: string | null; musicUrl?: string | null; utterances?: RuntimeUtterance[]; rootId?: string | null } +export type RuntimeNode = { id: string; kind: 'cutscene' | 'dialogue' | 'level'; label: string; componentKey?: string | null; levelSlug?: string | null; musicUrl?: string | null; musicVolume?: number; utterances?: RuntimeUtterance[]; rootId?: string | null } export type PlaythroughSummary = { id: string; mysterySlug: string; levelSlug: string | null; status: string } export type PlaythroughState = { playthrough: PlaythroughSummary; node: RuntimeNode | null }