DJ bot (voice audio)

import {
  Client,
  VoiceMediaSession,
  ffmpegResource,
  ytdlpResource,
  probeVoiceRuntime,
} from '@cloak-software/bot-sdk';
import type { AudioResource, VoiceConnection } from '@cloak-software/bot-sdk';

const client = new Client({
  token: process.env.CLOAK_TOKEN!,
  // Not optional, even for a toy. The bot's identity is published to the
  // server once and can never be republished. Omit this and the identity
  // lives only in this process: the first run works, and every restart after
  // it fails permanently.
  keystorePath: './dj-bot.cloak-keystore.json',
  requiredPermissions: ['view_text', 'message_send', 'commands', 'voice_connect', 'voice_speak'],
});

// userId -> channelId. The reverse of client.voiceRoster().
const whereTheyAre = new Map<string, string>();
client.on('voiceJoin', (p) => whereTheyAre.set(p.userId, p.channelId));
client.on('voiceLeave', ({ userId }) => whereTheyAre.delete(userId));

let conn: VoiceConnection | undefined;
let session: VoiceMediaSession | undefined;

// Pick the right decoder for what the user typed. Any http(s) url goes
// through yt-dlp: its generic extractor passes a direct media url straight
// through, so there is no need to guess which kind it is. Local paths skip it.
function resource(source: string): AudioResource | Promise<AudioResource> {
  return /^https?:\/\//i.test(source) ? ytdlpResource(source) : ffmpegResource(source);
}

async function leave(): Promise<void> {
  // Order matters: tear the media down before dropping the control-plane
  // membership, or the SFU keeps a publisher for a member who has left.
  try {
    await session?.detach();
  } finally {
    session = undefined;
    if (conn) {
      await client.leaveVoice().catch(() => undefined);
      conn = undefined;
    }
  }
}

client.commands.register(
  {
    name: 'play',
    description: 'play something in the voice channel you are in',
    options: [
      {
        name: 'source',
        type: 'string',
        description: 'a file path or a URL ffmpeg can read',
        required: true,
      },
    ],
  },
  async (ctx) => {
    const source = ctx.getString('source')!;

    // 1. Where is the invoker? If the bot has not seen them join, say so
    //    plainly rather than guessing. Joining the wrong channel is worse
    //    than refusing.
    const channelId = whereTheyAre.get(ctx.message.authorId);
    if (!channelId) {
      return void (await ctx.reply(
        'join a voice channel first, I only see members join while I am watching this server.',
      ));
    }

    // 2. Is the engine even installed? @livekit/rtc-node is an optional
    //    dependency, and on a fresh `npm i --omit=optional` it is not on
    //    disk. Probe rather than letting an import throw mid-join.
    const probe = await probeVoiceRuntime();
    if (!probe.available) {
      return void (await ctx.reply(`voice engine unavailable: ${probe.remedy}`));
    }

    await leave();

    // 3. Control plane. Deafened: the SFU then forwards this bot nothing.
    //    Slash commands are never dispatched from a DM, so serverId is
    //    non-null here.
    conn = await client.joinVoice(ctx.message.serverId!, channelId, { deafened: true });

    // 4. Key lane. A bot never derives a voice key, a human member seals one
    //    to it. This waits for that, and it is the step that hangs if nobody
    //    holding the server key is online.
    const voiceKey = await client.voiceKeys.acquireVoiceKey(ctx.message.serverId!);

    // 5. The scope is not this bot's choice: it is an authenticated tag
    //    inside the sealed blob. Publish-only means participant scope. Room
    //    scope would mean the server granted voice_listen and this bot could
    //    hear everyone, which is not what it advertises. Bail loudly instead
    //    of silently becoming a listening bot.
    if (voiceKey.scope !== 'participant') {
      await leave();
      return void (await ctx.reply(
        `this server granted me voice_listen (scope "${voiceKey.scope}") and I am deliberately ` +
          'publish-only. Revoke it, or run a bot that means to listen.',
      ));
    }

    // 6. Media. attach() installs the key BEFORE publishing. That order is
    //    load-bearing: publish first and the frame cryptor is created without
    //    a key, so the bot transmits audio nobody can decrypt, silently.
    session = await VoiceMediaSession.attach({
      url: conn.url,
      token: conn.token, // a live credential, never log it
      botId: client.user!.id,
      serverId: ctx.message.serverId!,
      voiceKey,
      keys: client.voiceKeys,
      deafened: conn.selfDeafened,
    });

    await ctx.reply(`playing in <#${channelId}>, I cannot hear any of you.`);
    try {
      // Resolves when the source ends. The awaited captureFrame inside is the
      // only pacer. There is no scheduler to add.
      await session.player.play(await resource(source));
    } catch (e) {
      // Report it in channel. A decoder failure is the most likely thing to
      // go wrong in a music bot, and it is the invoker, not the log, who
      // needs to know. CloakEnvironmentError carries a `remedy` for this.
      const err = e as Error & { remedy?: string };
      await leave();
      return void (await ctx.reply(
        `could not play that: ${err.message}${err.remedy ? `\n\n${err.remedy}` : ''}`,
      ));
    }
    await ctx.reply('finished');
  },
);

client.commands.register(
  { name: 'stop', description: 'stop playing and leave voice' },
  async (ctx) => {
    await leave();
    await ctx.reply('stopped');
  },
);

client.on('error', (e) => console.error('[dj-bot] error event:', e.message));

// A scope flip (voice_listen granted or revoked mid-call) re-pins at the SAME
// key version, so a handler keyed only on version would miss it. There is no
// key-removal API in the engine, so the only honest response to a scope change
// is to tear the session down.
client.on('voiceKeyUpdate', ({ scope }) => {
  if (session && scope !== 'participant') {
    console.warn('[dj-bot] scope changed to', scope, ', dropping the session');
    void leave();
  }
});

process.on('SIGINT', () => {
  void leave().finally(() => process.exit(0));
});

await client.login();
console.log('[dj-bot] ready, /play <source> in a text channel while sitting in voice');