raea/ask

Ask about a piece's picture and sound from a script: the same questions, runner and record as raea ask, typed.

View as Markdown

raea/ask asks from a script what raea ask asks from the command line: a script run with raea run, a .ts check, or plain Node or Bun. It runs raea ask --batch - --json, so every question about one clip goes in one call, the clips are cut once, the calls go in parallel, and every answer is kept for calibration. It pays the same way: your raea plan when the app is signed in, an agent key, or your own Cloudflare keys. It throws when nothing could be asked, and the error says why.

TS
import { ask, askMany } from "raea/ask";

const { answers } = ask("out/piece.mp4", "Does the music fight the voice?");
const run = askMany([
  { file: "out/a.mp4", set: "av", brief: "brief.ts" },
  { file: "out/b.mp4", std: ["defect.glitch"], window: { from: 0, to: 3 } },
]);
for (const a of run.answers) if (a.flagged) console.log(a.file, a.id, a.says, a.calibrated ? "finding" : "advice");
TS
import { ask, askMany, SETS } from "raea/ask"

raea/ask exports 2 functions, 1 value, 12 types. Source: sdk/raea/src/ask.ts.

Functions

ask

Questions about one file: your own words (yes or no), written-out questions, or with std/set the standard ones.

TS
function ask(file: string, question?: string | Question | (string | Question)[], more?: Omit<AskEntry, "file" | "questions"> & AskOptions): Asked

askMany

Many files asked in one run, in parallel; throws when nothing could be asked (the error says why).

TS
function askMany(entries: AskEntry[], o?: AskOptions): Asked

Values

SETS

Types

Answer

One question's answer, or why it wasn't asked or still waits: a line of raea ask --json.

FieldTypeWhat it is
answerstringits id in the record, for raea ask verdict
file (required)stringthe file asked about
id (required)stringthe question's id
version (required)stringa hash of its words, type and options: a new wording is a new version, calibrated on its own
from (required)numberthe window's start, in seconds
tonumberthe window's end, in seconds (unset: the file's end)
saysstringthe answer in words with its probability
valuenumberyes's probability, a pick's probability, or a level
problemnumber0 to 1, higher is likelier a problem (none for a pick)
choicestringthe option or level chosen
flagged (required)booleanpast the question's threshold (its calibrated one, else even odds)
calibrated (required)booleanits labels separate well enough for its answers to be findings; until then they're advice
not_askedstringwhy it wasn't asked (it doesn't apply to this piece, or the call failed)
waitsstringwhy it still waits (this month's pool is spent)
routestringthe way it was paid: your raea plan through the app, an agent key, or your Cloudflare account
cached (required)booleananswered from the cache, at no cost

Asked

A run's answers, the calls dry would make, and its summary.

FieldTypeWhat it is
answers (required)Answer[]every question's answer, or why it wasn't asked, in the order they came
would (required)unknown[]with dry: each call that would be made (its state, questions, media sizes and estimate)
summary (required)Summarywhat it came to

AskEntry

One file and what to ask of it: a line of raea ask --batch.

FieldTypeWhat it is
file (required)stringthe video, sound or picture asked about
questions(string | Question)[]questions in your own words (yes or no) or written out
setstring | string[]standard sets by name: rubric, av, defects, platform, decide
stdstring[]standard questions by id (raea ask list lists them)
windowWindowthe seconds to look at, for every question here (else each question's own, else the whole file)
withstring[]files set beside it: to pick between, or a before and after
briefstringthe project's brief (else the nearest brief.ts above the file; "none": no brief, the state saying what the piece is)
wordsstringa words file (a JSON list of the words heard), so ask knows what's said and whether anyone speaks
voicebooleanwhether anyone speaks in it, when no words file says
statestringmore for clef to read before the media: what raea measured, the platform

AskOptions

How a run goes.

FieldTypeWhat it is
jobsnumbercalls at once (4 unless set)
drybooleancut the media and say what would be sent, spending nothing
binstringthe raea to run (RAEA_BIN, else raea on the PATH)

Calibration

TS
type Calibration = { auc: number, n: number, positives: number, /** * the problem score at which it flags (10% false positives on its labels) */ threshold?: number, /** * YYYY-MM-DD */ date: string, /** * whose labels: "raea" (raea's bench, shipped) or "you" */ by: string, }

Kind

TS
type Kind = "yes" | "choose" | "grade" | "rate"

Picks

TS
type Picks = "all" | "after-first"

Question

TS
type Question = { /** * letters, digits, `_`, `.` and `-` */ id: string, /** * the question in words, as clef reads it */ ask: string, type?: Kind, /** * choose: its options; grade and rate: its levels, lowest first (a grade's are LEVELS unless given) */ options?: Array<string>, /** * what an option (or yes and …

Sees

TS
type Sees = "video" | "stills" | "nothing"

Summary

What a run came to.

FieldTypeWhat it is
asked (required)numberthe questions sent
answered (required)numberthe answers read
calls (required)numberthe calls made (with dry, the calls that would be)
cost (required)numberwhat the calls cost, in dollars
estimate (required)numberwith dry, what the calls would cost, in dollars
pool_leftnumberwhat's left of this month's pool, in dollars, when the plan paid
waiting (required)numberthe questions waiting for the pool
flagged (required)numberthe answers past their threshold
flagged_calibrated (required)numberthe calibrated answers past their threshold: findings
routes (required)string[]the ways the calls were paid
clips (required)numberthe clips cut, each once

When

TS
type When = { /** * the brief's modes it's for (pitch, story, explain, play, tool); empty is every mode */ modes?: Array<string>, /** * true: only when someone is heard speaking; false: only when no one is */ voice?: boolean, /** * true: only for a game; false: never for one */ game?: boolean, }

Window

TS
type Window = { from?: number, to?: number, }