The scripting API.

interface OtDispatchedEvent {
  type: string;        // e.g. 'alert.redemption'
  payload: unknown;    // the event data; fields depend on type
  params: unknown;     // data for a companion-trigger dispatch
  isTest: boolean;     // true for a Test-fire from the dashboard
  occurredAt: string;  // ISO timestamp
}

ot.on('alert.follower', (e) => {
  ot.log('New follower:', e.payload.username);
});

// Ignore dashboard Test-fires for this one
ot.on('alert.subscriber', (e) => { /* ... */ }, { skipTest: true });

ot.onHotkey(combo: string, handler): void   // a global keyboard shortcut
ot.onSchedule(spec: string, handler): void   // a cron-like timer, e.g. '@every 5m'

ot.onHotkey('ctrl+alt+d', () => ot.obs.setScene('BRB'));
ot.onSchedule('@every 5m', () => ot.chat.send('Remember to hydrate!'));

ot.log(...args): void
ot.now(): number                              // ms since the Unix epoch
ot.wait(ms): Promise<void>                    // (ot.sleep is an alias)

ot.store.get<T>(key): Promise<T | undefined>  // persisted per script
ot.store.set(key, value): Promise<void>
ot.store.delete(key): Promise<void>
ot.store.sadd(key, member): Promise<boolean>       // add to a set, true if new
ot.store.sismember(key, member): Promise<boolean>  // is it in the set?
ot.store.scard(key): Promise<number>              // set size

ot.state.media: OtMediaSnapshot               // now-playing, queue, volume

// Greet each viewer's first message, using a persisted set
ot.on('chat.message', async (e) => {
  const user = String(e.payload.username);
  if (await ot.store.sismember('greeted', user)) return;
  await ot.store.sadd('greeted', user);
  ot.chat.send('Welcome, ' + user + '!');
});

ot.key(combo: string): void                  // ONE chord, held together
ot.type(text: string): void                  // type literal text
ot.hotkey(combos: string[]): void            // a SEQUENCE of combos (a macro)
ot.mouse.move(x: number, y: number): void
ot.mouse.click(button?: 'left' | 'right' | 'middle'): void

// A redemption presses your OBS replay-save hotkey
ot.on('alert.redemption', (e) => {
  if (e.payload.reward_title !== 'Save That') return;
  ot.key('cmd+shift+f4');  // 👉 EDIT: your own hotkey
});

ot.run(command: string, args?: string[]): Promise<{ code: number; stdout: string; stderr: string }>
ot.open(target: string): void   // open a URL, file, or app

ot.onHotkey('ctrl+alt+s', async () => {
  const r = await ot.run('say', ['stream starting']);
  ot.log('exit', r.code);
});

ot.playSound(path: string, opts?: { volume?: number }): void   // volume 0..1

ot.on('alert.cheer', (e) => {
  if (e.payload.bits >= 1000) ot.playSound('/Users/you/Sounds/airhorn.mp3', { volume: 0.6 });
});

ot.fetch(url: string, init?: OtFetchInit): Promise<OtFetchResponse>

interface OtFetchInit {
  method?: string;                        // defaults to 'GET'
  query?: Record<string, string | number>; // percent-encoded for you
  headers?: Record<string, string>;
  json?: unknown;                         // JSON-serialized request body
}
interface OtFetchResponse {
  status: number;   // 0 on a transport failure
  ok: boolean;      // true for a 2xx
  json?: unknown;   // parsed body when JSON
  text: string;
  headers: Record<string, string>;
  error?: string;   // present only on a transport failure
}

ot.on('chat.message', async (e) => {
  if (e.payload.message_text !== '!weather') return;
  const r = await ot.fetch('https://wttr.in/London', { query: { format: '3' } });
  if (r.ok) ot.chat.send(r.text);
});

ot.obs.setScene(sceneName: string): Promise<void>
ot.obs.setInputMute(inputName: string, muted?: boolean): Promise<void>
ot.obs.toggleSource(inputName: string): Promise<void>
ot.obs.call<T>(requestType: string, requestData?: unknown): Promise<T>

ot.onHotkey('ctrl+alt+b', async () => {
  await ot.obs.setInputMute('Mic', true);
  await ot.obs.setScene('BRB');       // 👉 EDIT: your scene names
});

ot.chat.send(text: string): Promise<void>
ot.chat.reply(e: { user?: string }, text: string): Promise<void>
ot.flow.emit(name: string, payload?: unknown): Promise<void>

// Reply 'splat' whenever someone says 'whee'
ot.on('chat.message', (e) => {
  const text = String(e.payload.message_text ?? '').toLowerCase();
  if (/\bwhee\b/.test(text)) {
    ot.chat.reply({ user: e.payload.username }, 'splat');
  }
});