@deadair/plugin-sdk 0.2.4 → 0.3.0

package/README.md

@@ -720,7 +720,10 @@ The host never interprets that string, and that is deliberate. It is what lets
 one station voice be a named preset on one engine and a cloned reference clip on
 another, so swapping engines does not rewrite every persona. Engine-specific
 tuning belongs in your config, not in the request: the host should not be
-carrying knobs only one implementation understands.
+carrying knobs only one implementation understands. The one thing about a
+reading it does carry is a delivery, and that is a word rather than a knob; see
+[Cues and deliveries](#cues-and-deliveries).
+
 
 Implement `listVoices()` if you have more than one, so the console can draw a
 list and preview them. It is optional, and a single-voice plugin is a legitimate
@@ -746,8 +749,53 @@ than `select` — a cell with choices renders as an autocomplete, so a value you
 list cannot enumerate (a blend expression, a clip added a minute ago) stays
 typeable.
 
+### Cues and deliveries
+
+Two things about how a line is performed reach you in the STATION's words, and
+both work the same way. The station names what it wants, you say which of those
+your engine can do right now, and you translate each one into whatever your
+engine actually takes. Nothing engine-specific ever crosses the boundary, so a
+station can change engines without rewriting a single script.
+
+- **A cue** is something a presenter does at a place in a sentence: `[laugh]`,
+  `[sigh]`, the rest of `SPEECH_CUES`. It rides inside `SpeechRequest.text`,
+  because where it happens is part of what it is. Claim the ones you perform with
+  `listCues()`.
+- **A delivery** is how the WHOLE line is read: `hushed` or `frantic`, the whole
+  of `SPEECH_DELIVERIES`. It rides beside the text as `SpeechRequest.delivery`,
+  and absent is the voice's own ordinary reading. Claim the ones you perform with
+  `listDeliveries()`.
+
+The host strips every cue and drops every delivery you did not claim before it
+calls `speak`, and the model writing a break is only offered what you claimed.
+So implementing neither is always safe: your engine never sees a word it would
+read aloud or ignore. The one way to break it is to claim something you cannot
+perform.
+
+**Answer from what the engine IS right now**, not from what you were built
+against. On the engine these were written for, the loaded MODEL decides: one
+build performs cues and ignores expressiveness, the others do the opposite. So
+both methods ask the server and answer empty when it cannot be reached.
+
+**Translate relative to the voice, not to a fixed point.** A delivery is a
+direction from wherever the voice already is, so a character who is intense at
+rest stays more intense than their neighbours when hushed. Two sketches of the
+same word on different engines:
+
+```ts
+// An engine with expressiveness dials, tuned per voice in your own config.
+const frantic = { exaggeration: clamp(voice.exaggeration + 0.4), cfg_weight: voice.cfgWeight };
+
+// An engine with only a speed.
+const hushed = { speed: (voice.speed ?? 1) * 0.9 };
+```
+
+The numbers belong to you and live in your config beside the voice they tune.
+The host never sees them, which is why the station's side of this is a word.
+
 ## Producing words
 
+
 A plugin that declares `llm` continues a conversation. It is a **transport, not a
 writer**: nothing in this capability knows what a break, a show or a running
 order is, because deciding what to say is the station's business and the shapes

package/dist/capabilities/speech.d.ts

@@ -28,6 +28,15 @@
  * inside your own config where it belongs, rather than asking the host to carry
  * knobs only you understand.
  *
+ * ## A delivery is a word the station chose, too
+ *
+ * The one thing about HOW a line is read that the host does carry is
+ * {@link SpeechRequest.delivery}: `hushed` or `frantic`, in the station's words
+ * and never as a number. That is the same bargain as a voice and a cue. The host
+ * says what it wants in a vocabulary every engine can be asked in, and each plugin
+ * translates it into whatever its engine has, whether that is an expressiveness
+ * dial, a speed, a style preset or nothing at all. The numbers stay in your config.
+ *
  * Every shape here is JSON-safe.
  */
 import type { PluginLifecycle } from '../plugin.lifecycle.js';
@@ -89,6 +98,37 @@ export declare function cuesIn(text: string): SpeechCue[];
  * and stays exactly as it arrived: this is not a bracket stripper.
  */
 export declare function withoutCues(text: string, keep?: Iterable<SpeechCue>): string;
+/**
+ * How a whole line is read, as the station names it.
+ *
+ * Two, and the middle is deliberately not one of them: a request with no delivery is the voice's own
+ * ordinary reading, which is what nearly every line should be. A third word for "ordinary" would be a
+ * second way to ask for nothing, and would key a second cached preview of identical audio.
+ *
+ * The vocabulary is the STATION's and translating it is yours, exactly as for {@link SPEECH_CUES}.
+ * `hushed` is quieter, slower, closer to the microphone; `frantic` is urgent, faster, barely holding
+ * on. Whether your engine gets there with an expressiveness dial, a speed, a style token or a
+ * different reference clip is engine business, and the host never learns which.
+ *
+ * ## Why a word and not a number
+ *
+ * A number is a promise about one engine's scale. `exaggeration: 0.9` means something to one family of
+ * models and nothing to the next, so a station that asked for it would be tied to the engine it was
+ * built against, which is the thing the voice indirection exists to prevent. A word survives a change
+ * of engine. The numbers it becomes live in each plugin's own config, beside the voice they tune.
+ *
+ * ## Claim only what you can perform
+ *
+ * {@link SpeechPluginInstance.listDeliveries} says which of these your engine can do RIGHT NOW, and the
+ * host drops any delivery you did not claim before it calls {@link SpeechPluginInstance.speak}. So a
+ * plugin that implements nothing here never sees one, and the writer is never offered a delivery the
+ * engine would ignore. Claiming one you cannot perform is the only way to break it.
+ */
+export declare const SPEECH_DELIVERIES: readonly ["hushed", "frantic"];
+/** One of {@link SPEECH_DELIVERIES}. */
+export type SpeechDelivery = (typeof SPEECH_DELIVERIES)[number];
+/** Whether a value is one of {@link SPEECH_DELIVERIES}, exactly as written. */
+export declare function isSpeechDelivery(value: unknown): value is SpeechDelivery;
 /** One thing to say. */
 export interface SpeechRequest {
     /**
@@ -112,6 +152,15 @@ export interface SpeechRequest {
      * that instead. Ignore it entirely if your engine emits one format.
      */
     format?: string;
+    /**
+     * How to read the whole line, or absent for the voice's own ordinary reading.
+     *
+     * Only ever one you claimed through {@link SpeechPluginInstance.listDeliveries}: the host drops the
+     * rest before this call. Translate it into your engine's own controls, relative to whatever the
+     * voice already sounds like, so a voice that is intense at rest is still more intense than its
+     * neighbours when hushed. See {@link SPEECH_DELIVERIES}.
+     */
+    delivery?: SpeechDelivery;
 }
 /** The audio for one {@link SpeechPluginInstance.speak}, and what it is. */
 export interface SpeechHandle {
@@ -207,5 +256,19 @@ export interface SpeechPluginInstance extends PluginLifecycle {
      * not fail to write one.
      */
     listCues?(): Promise<readonly SpeechCue[]>;
+    /**
+     * Which of {@link SPEECH_DELIVERIES} this plugin can perform RIGHT NOW.
+     *
+     * Optional, and absent means none, for the reason {@link listCues} gives: most engines have no
+     * such control, and saying nothing costs a plugin nothing because the host drops what you do not
+     * claim.
+     *
+     * The same three rules as for cues, too. Answer from what the engine currently IS, since on some
+     * engines the control belongs to the loaded model rather than to the server. Keep it cheap,
+     * because it is asked on the path that writes a break. And answer empty rather than throwing when
+     * the engine cannot be reached, because a station that cannot ask should write an ordinary
+     * reading rather than fail to write one.
+     */
+    listDeliveries?(): Promise<readonly SpeechDelivery[]>;
 }
 //# sourceMappingURL=speech.d.ts.map

package/dist/capabilities/speech.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"speech.d.ts","sourceRoot":"","sources":["../../src/capabilities/speech.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,WAAW,0FAA2F,CAAC;AAEpH,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAEhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,CAAC,SAAS,CAAM,GAAG,MAAM,CAQhF;AAYD,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IACzB;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IACxB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IACzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"speech.d.ts","sourceRoot":"","sources":["../../src/capabilities/speech.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,WAAW,0FAA2F,CAAC;AAEpH,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAEhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,CAAC,SAAS,CAAM,GAAG,MAAM,CAQhF;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,gCAAiC,CAAC;AAEhE,wCAAwC;AACxC,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IACzB;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IACxB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IACzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IAE3C;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAC;CACzD"}

package/dist/index.js

@@ -291,6 +291,14 @@ __name(withoutCues, "withoutCues");
 var cuePattern = /* @__PURE__ */ __name(() => new RegExp(`\\[(${[
   ...SPEECH_CUES
 ].sort((left, right) => right.length - left.length).join("|")})\\]`, "gi"), "cuePattern");
+var SPEECH_DELIVERIES = [
+  "hushed",
+  "frantic"
+];
+function isSpeechDelivery(value) {
+  return typeof value === "string" && SPEECH_DELIVERIES.includes(value);
+}
+__name(isSpeechDelivery, "isSpeechDelivery");
 
 // src/plugin.http.ts
 var MAX_UPSTREAM_MESSAGE = 200;
@@ -1101,6 +1109,7 @@ export {
   PluginError,
   ROW_ID_KEY,
   SPEECH_CUES,
+  SPEECH_DELIVERIES,
   baseForm,
   collectGeneration,
   configBaseUrl,
@@ -1126,6 +1135,7 @@ export {
   isPluginError,
   isResourceScopedCode,
   isRowSecretKey,
+  isSpeechDelivery,
   isZodSchema,
   jsonBody,
   networkPermissionSchema,