diff options
Diffstat (limited to 'docs/superpowers/specs')
| -rw-r--r-- | docs/superpowers/specs/2026-10-23-companion-design.md | 13 | ||||
| -rw-r--r-- | docs/superpowers/specs/2026-10-23-companion-music-design.md | 125 |
2 files changed, 132 insertions, 6 deletions
diff --git a/docs/superpowers/specs/2026-10-23-companion-design.md b/docs/superpowers/specs/2026-10-23-companion-design.md index 03feaff..8a8c426 100644 --- a/docs/superpowers/specs/2026-10-23-companion-design.md +++ b/docs/superpowers/specs/2026-10-23-companion-design.md @@ -111,7 +111,7 @@ base, so every frame descends from one reference. | --- | --- | | klein edit of `base-sitting.png` | `base`: "make her stand upright, facing the viewer, arms relaxed at her sides" | | img2img from `base`, strength 0.75 | `smile`, `mad`, `smirk`, `blush1`, `blush2`, `blush3`, `sleepy` | -| klein edit of `base` | `wave`, `watch`, `point`, `yawn`, `lying`, `listen`, `think`, `muse`, `stretch`, `shoved` | +| klein edit of `base` | `wave`, `watch`, `point`, `yawn`, `lying`, `listen`, `think`, `muse`, `stretch`, `shoved`, `sing` | | klein edit of the dress frame | every `leotard/<name>`: "her skirt is gone, revealing a plain white leotard; change nothing else" | | klein edit of `leotard/base` | `scorched`, leotard only: the moment after the explosion | @@ -137,11 +137,12 @@ timers. | 2 | Dodge | pointer rests on her 0.6 s with no click | slides out of the corner | returns after 5 s | | 3 | Shoved | a balloon is on screen on her monitor | `shoved`, slid left by the stack's width | balloons gone | | 4 | Assistant | recording / working / reply arrived | `listen` / `think` / `wave` | state ends; wave lasts 3 s | -| 5 | Clicks | clicks 1-6 of a burst; a burst ends after 1.5 s without one | `smile`, `blush1` to `blush3` | 2 s after the last click | -| 6 | Mock | BackSpace, at most once in 20 s | `smirk`, `point` | 2.5 s | -| 7 | Watching | typing pulse in the last 2 s | `watch` | 2 s after typing stops | -| 8 | Idle | no input for 1 / 3 / 5 min | `sleepy` / `yawn` / `lying` | any input: `stretch`, then base | -| 9 | Base | nothing else | `base` | | +| 5 | Singing | Sony headphones connected | `sing` | 4 s | +| 6 | Clicks | clicks 1-6 of a burst; a burst ends after 1.5 s without one | `smile`, `blush1` to `blush3` | 2 s after the last click | +| 7 | Mock | BackSpace, at most once in 20 s | `smirk`, `point` | 2.5 s | +| 8 | Watching | typing pulse in the last 2 s | `watch` | 2 s after typing stops | +| 9 | Idle | no input for 1 / 3 / 5 min | `sleepy` / `yawn` / `lying` | any input: `stretch`, then base | +| 10 | Base | nothing else | `base` | | - **Self-destruct, as in the game.** She glows, says "Self-destruct sequence initiated.", a white flash covers the sprite for about a diff --git a/docs/superpowers/specs/2026-10-23-companion-music-design.md b/docs/superpowers/specs/2026-10-23-companion-music-design.md new file mode 100644 index 0000000..dc30257 --- /dev/null +++ b/docs/superpowers/specs/2026-10-23-companion-music-design.md @@ -0,0 +1,125 @@ +# Companion music: design + +Date: 2026-10-23. Status: designed, not implemented. + +## Goal + +The companion reacts to what is playing, not only to headphones +connecting. When a track starts or changes she DJs behind a console for a +few seconds, and says a line if she knows the artist. While music plays +and she is bored, she grooves instead of looking sleepy: whistling, +headbanging or playing air guitar, with an occasional line. Her artist +lines are edited in Settings > Companion artists, like the app lines. + +## Verified before designing + +- **`modules/sound/Player.qml` already picks the real player.** It is a + singleton the island reads, filters out the playerctld and + plasma-browser-integration duplicates, and exposes `playing`, `artist` + and `title`. The companion reads it; it opens no MPRIS of its own. +- **The app lines page is one parameter away from serving artists.** + `PhrasesPage.qml` edits a list of `{cls, lines}` owned by + `PhrasesModule.qml`, which saves through `Prefs.setCompanionApps` and + falls back to `Lines.apps`. Only the key's label is app specific. + +## Behaviour + +### DJ burst + +A track key is `artist + "\n" + title`. While `Player.playing` is true, a +key different from the last one seen sets `djAt` to now and becomes the +last one seen. Resuming the same track after a pause is not a change, so +it does not DJ. A shell start with music already playing does DJ once: +unlike Bluetooth, MPRIS has no empty startup window to mistake for a +connection, and a DJ on launch is harmless. + +`Mood.T.djHold` is 6000. In `Mood.pick` the DJ ranks directly below +`sing`, so headphones connecting together with music starting sings +first. Its frames are `dj` and `dj-scratch`, cycled by Companion.qml the +way the wave frames are. + +On the burst she says an artist line if one matches, under the 30 s line +cooldown. No match says nothing. + +### Artist matching + +`Lines.artistLine(map, artist)`: the first key of the map that is a +case-insensitive substring of the reported artist wins, and one of its +lines is picked at random. "daft punk" matches "Daft Punk, Pharrell +Williams". Short keys can over-match ("air" in "Airbourne"); accepted. + +### Groove + +`Mood.pick` gains `s.music` (`Player.playing`). At `idle === 1` with +music, the state is `groove` instead of `bored`; yawning and lying down +are unchanged, so music does not stop her dozing off and the screensaver +handoff stays the same. + +Reaching idle stage 1, or music starting while already there, picks one +groove at random: `whistle`, `headbang` or `airguitar`; an unset pick +reads as `whistle`. The pick is passed to `pick` as `s.groove`, so +`Mood.js` stays pure. Headbang cycles `headbang-up` and `headbang-down` +fast; the other two are single frames. + +The bored line becomes a `groove` line when music is playing, same +chance, same cooldown. The opening monologue keeps its bored trigger +only when there is no music. + +## Lines + +New reaction group in `Lines.lines`: + + groove: ["This one's good.", "...Don't tell 9S.", "Again. Play it again."], + +Default artists, `Lines.artists`: + + "linkin park": ["In the end, it doesn't even matter.", "Crawling in my skin... I know this one."], + "evanescence": ["Wake me up inside. ...Operator, don't laugh."], + "gigi d'agostino": ["L'amour toujours. I'll fly with you.", "...My feet are moving on their own."], + "eminem": ["Lose yourself. Understood.", "He talks faster than Pod."], + +`appList` and `toMap` take the default set as an argument, so the same +functions serve apps and artists; `appMap` becomes `pickMap(saved, +defaults)`. + +## Settings + +- `Prefs.companionArtists`, `setCompanionArtists`, `resetCompanionArtists`, + parsed and defaulted like `companionApps`. +- `PhrasesPage.qml` gains `keyLabel` (default "Class") used for the key + field's placeholder and label. +- `modules/companion/ArtistsModule.qml`: "Companion artists", group + Companion, a copy of `PhrasesModule` bound to the artist prefs and + defaults, `keyLabel: "Artist"`. Registered in `shell.qml`, which means a + restart (see AGENTS.md, Reloading). + +## Frames + +In `frames.txt`, each with its leotard line (`${LEOTARD}`), 12 in all: + + DECK = A small black DJ console with two turntables and a mixer stands in front of her at waist height, hiding her legs. + dress/dj <- dress/base : ${DECK} Both gloved hands rest on the turntables, head nodding, a small smile; she wears black over-ear headphones. ${EYES} ${KEEP} + dress/dj-scratch <- dress/dj : Change only her arms: the hand on the left side of the image scratches a record, the other holds one headphone cup to her ear. Everything else exactly the same. ${KEEP} + dress/whistle <- dress/base : Change only her expression: lips puckered, whistling, a couple of small black musical notes floating beside her mouth. ${POSE} ${EYES} ${KEEP} + dress/headbang-up <- dress/base : She headbangs: head tipped back, hair flying up, eyes shut, fists clenched at her sides. ${BARE} ${KEEP_BARE} + dress/headbang-down <- dress/headbang-up : Change only her head: tipped sharply forward and down, hair thrown forward over her face. Everything else exactly the same. ${KEEP_BARE} + dress/airguitar <- dress/base : She plays an invisible air guitar: one hand strumming at her hip, the other fretting in the air to the side, knees bent, eyes shut, mouth open in a grin. Nothing in her hands. ${BARE} ${KEEP_BARE} + +Prompts are a first draft: klein results get rerolled and reworded as +before, and what failed goes into `recipe.txt`. The user runs +`gen-frames`; a missing frame falls back to `base`, so the code can land +before the art. + +## Tests + +- `test_mood.js`: dj wins over clicks and loses to sing; groove replaces + bored only with music; yawn and lying still win with music; groove + frame follows `s.groove`. +- `test_lines.js`: substring match is case-insensitive and picks the + first matching key; no match returns nothing; `appList`/`toMap` round + trip with the artist defaults. + +## Not doing + +- Window title or URL reactions (separate idea, not this spec). +- Per-artist frames, genre detection, beat sync. |