nixamp 0.63.3 → 0.65.1

package/src/ai-label.ts

@@ -33,7 +33,7 @@ import { dirname, join, resolve, sep } from "node:path";
 import { aiKey } from "./ai-keys.ts";
 import { composerFromEnv, OutOfCredit, type Composer } from "./ai-radio.ts";
 import { askJson, hasModel } from "./ai-text.ts";
-import { formatLrc, type SyncedLine } from "./lyrics.ts";
+import { formatLrc, parseLrc, type SyncedLine } from "./lyrics.ts";
 import { bandMarkdown, castLine, inventMembers, readMembers, writeMembers, type Member } from "./label-profiles.ts";
 import type { LibraryIndex, Probed } from "./library-index.ts";
 import type { StationRunner } from "./station-runner.ts";
@@ -127,8 +127,10 @@ export interface LabelSettings {
   videos: boolean;
   /** Each album's single (song 1) is filmed with Veo, while the month's Veo budget lasts. */
   veo: boolean;
-  /** How many 8 s Veo shots a single is cut from. */
+  /** How many 8 s Veo shots of the band a single is cut from. */
   veoShots: number;
+  /** How many close-ups of the singer a single gets, lip-synced to the song (0: none, the band only). */
+  lipsyncShots: number;
   /** Public, listed and owned, so the genre stations are on the guide. */
   publish: boolean;
   /** Songs made at the same time (ElevenLabs takes several requests at once on a paid plan). */
@@ -384,6 +386,7 @@ export const DEFAULTS: Omit<LabelSettings, "pausedReason"> = {
   videos: true,
   veo: false,
   veoShots: 6,
+  lipsyncShots: 2,
   parallel: 1,
   genreOrder: ["Punk", "Blues", "Country", "Jazz", "Classic Rock", "Metal", "Hip-Hop", "Pop", "R&B"],
 };
@@ -640,18 +643,31 @@ const SHOTS = [
   "The band walking out on stage before the show, backlit silhouettes, nobody speaking or singing",
 ];
 
+// The singer's close-ups, which are lip-synced to the song afterwards (fal.ai). The mouth
+// must be clear: whatever covers it (a microphone, a hand) is smeared into the face when
+// the mouth is redrawn.
+const CLOSE_UPS = [
+  "Medium close-up of the lead vocalist singing straight to camera, the microphone stand lowered to chest height so the whole mouth and chin are clear, nothing in front of the face",
+  "Close-up of the lead vocalist singing with feeling, head and shoulders, a handheld microphone held down at the chest, the whole mouth clearly visible",
+  "Medium shot of the lead vocalist singing to the crowd, the microphone held out to the side, face lit and the mouth fully visible",
+  "Close-up of the lead vocalist singing in profile-three-quarter view, no microphone in frame, the mouth clearly visible",
+];
+
 /**
  * The prompts for a single's filmed shots. The people are the reference
  * images, described by role and look only: Veo refuses names with faces
  * ("we can't create videos with real people's names or likenesses").
  */
-export function veoPrompts(artist: Pick<LabelArtist, "genre" | "sound">, song: Pick<LabelSong, "style">, members: Array<Pick<Member, "role" | "look">>, count: number): string[] {
+export function veoPrompts(artist: Pick<LabelArtist, "genre" | "sound">, song: Pick<LabelSong, "style">, members: Array<Pick<Member, "role" | "look">>, count: number, kind: "band" | "singer" = "band"): string[] {
   const cast = members.slice(0, 3).map((one, i) => `the ${one.role} from reference image ${i + 1} (${one.look.replace(/\b[A-Z][a-z]+ [A-Z][a-z]+\b/g, "")})`).join("; ");
-  return SHOTS.slice(0, count).map((shot) => [
+  const rule = kind === "singer"
+    ? "The vocalist sings clearly, the whole mouth always visible, never covered by a microphone or a hand. Cinematic, 35mm film look. No text, no logos."
+    : "Nobody sings, speaks or lip-syncs on camera: no mouths in close-up. Cinematic, 35mm film look, dynamic camera. No text, no logos.";
+  return (kind === "singer" ? CLOSE_UPS : SHOTS).slice(0, count).map((shot) => [
     `Music video for a fictional ${artist.genre} band. ${shot}.`,
     cast ? `The performers are exactly the people in the reference images: ${cast}.` : "",
     `Mood and sound: ${song.style} ${artist.sound}.`.slice(0, 400),
-    "Nobody sings, speaks or lip-syncs on camera: no mouths in close-up. Cinematic, 35mm film look, dynamic camera. No text, no logos.",
+    rule,
   ].filter(Boolean).join(" "));
 }
 
@@ -736,8 +752,29 @@ export function renderStoryVideo(ffmpeg: string[], input: { audio: string; image
 }
 
 /**
- * The version of a video cut from Veo footage with nobody singing on camera; anything
- * older (a slideshow, or 4: footage whose singers were out of sync) is not shown.
+ * Where a single's lip-synced close-ups go: the start of a sung line (its .lrc)
+ * nearest a quarter and three quarters in (one: a third in), each `length`
+ * seconds, after the title card, never overlapping. Without timed words, those
+ * points themselves.
+ */
+export function closeUpTimes(seconds: number, lines: Array<{ start: number }>, count: number, length = 8): number[] {
+  if (count < 1) return [];
+  const targets = count === 1 ? [1 / 3] : Array.from({ length: count }, (_, i) => 0.25 + (0.5 * i) / (count - 1));
+  const fits = (t: number): boolean => t >= 6 && t + length <= seconds - 1;
+  const starts = lines.map((line) => Math.round(line.start * 100) / 100).filter(fits);
+  const chosen: number[] = [];
+  for (const share of targets) {
+    const want = share * seconds;
+    const pool = (starts.length ? starts : [Math.round(want)]).filter((t) => fits(t) && chosen.every((one) => Math.abs(one - t) >= length));
+    if (pool.length) chosen.push(pool.reduce((best, t) => (Math.abs(t - want) < Math.abs(best - want) ? t : best)));
+  }
+  return chosen.sort((a, b) => a - b);
+}
+
+/**
+ * The version of a video cut from Veo footage: the band with nobody singing, and the
+ * singer only in close-ups lip-synced to the song. Anything older (a slideshow, or 4:
+ * footage whose singers were out of sync) is not shown.
  */
 export const FILMED = 5;
 
@@ -747,17 +784,32 @@ export const FILMED = 5;
  * ends, so no picture holds still. The artist and title come up at the start;
  * the MP3's audio and tags are copied in. 1080p H.264.
  */
-export function renderFilmedVideo(ffmpeg: string[], input: { audio: string; clips: Array<{ path: string; seconds: number }>; seconds: number; artist: string; title: string; out: string }): Promise<void> {
+export function renderFilmedVideo(ffmpeg: string[], input: { audio: string; clips: Array<{ path: string; seconds: number }>; seconds: number; artist: string; title: string; out: string; pinned?: Array<{ path: string; at: number; seconds: number }> }): Promise<void> {
   if (input.clips.length === 0) return Promise.reject(new Error("no footage to cut"));
   const cut = 4;
+  // Lip-synced close-ups play whole at the second of the song they were synced to; the band fills around them.
+  const pinned = [...(input.pinned ?? [])].sort((a, b) => a.at - b.at);
   const cuts: Array<{ path: string; start: number; length: number }> = [];
-  for (let at = 0, i = 0; at < input.seconds; i++) {
+  for (let at = 0, i = 0; at < input.seconds - 0.05;) {
+    const pin = pinned.find((one) => Math.abs(one.at - at) < 0.05);
+    if (pin) {
+      const length = Math.min(pin.seconds, input.seconds - at + 0.5);
+      cuts.push({ path: pin.path, start: 0, length });
+      at += length;
+      continue;
+    }
+    const next = pinned.find((one) => one.at > at + 0.05);
     const clip = input.clips[i % input.clips.length]!;
     const half = Math.floor(i / input.clips.length) % 2;
-    const start = Math.min(half * cut, Math.max(0, clip.seconds - cut));
-    const length = Math.min(cut, clip.seconds - start, input.seconds - at + 0.5);
+    let length = Math.min(cut, input.seconds - at + 0.5);
+    // Up to a close-up: one cut to meet it exactly, never a sliver.
+    if (next) length = next.at - at < cut * 1.5 ? next.at - at : Math.min(length, next.at - at);
+    const start = length > cut ? 0 : Math.min(half * cut, Math.max(0, clip.seconds - cut));
+    length = Math.min(length, clip.seconds - start);
+    if (length < 0.04) break;
     cuts.push({ path: clip.path, start, length });
     at += length;
+    i += 1;
   }
   const parts = cuts.map((_, i) => `[${i}:v]scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,fps=25,setsar=1,setpts=PTS-STARTPTS[c${i}]`);
   parts.push(`${cuts.map((_, i) => `[c${i}]`).join("")}concat=n=${cuts.length}:v=1:a=0[cut]`);
@@ -864,7 +916,9 @@ export interface AiLabelDeps {
   /** How long to wait before asking Veo again after nixamp.com or the network failed (60 s). */
   retryMs?: number;
   /** Cuts a single's filmed shots to its song; ffmpeg by default (renderFilmedVideo). */
-  filmedVideo?: (input: { audio: string; clips: Array<{ path: string; seconds: number }>; seconds: number; artist: string; title: string; out: string }) => Promise<void>;
+  filmedVideo?: (input: { audio: string; clips: Array<{ path: string; seconds: number }>; seconds: number; artist: string; title: string; out: string; pinned?: Array<{ path: string; at: number; seconds: number }> }) => Promise<void>;
+  /** A singer's close-up with the mouth redrawn to these seconds of the song (nixamp.com, fal.ai); VeoUnavailable when the month is spent. */
+  lipsync?: ((input: { video: Buffer; audio: Buffer; seconds: number }) => Promise<Buffer>) | null;
   /** Renders a storyboard music video; ffmpeg by default (renderStoryVideo). */
   storyVideo?: (input: { audio: string; images: string[]; seconds: number; artist: string; title: string; out: string; clips?: Array<{ path: string; seconds: number }> }) => Promise<void>;
   /** A scene's picture for this prompt, or null when nothing can draw one; Workers AI by default. */
@@ -1051,6 +1105,8 @@ export class AiLabel {
     if (input["veo"] !== undefined) this.settings.veo = input["veo"] === true;
     const shots = whole("veoShots", 1, 8);
     if (shots !== undefined) this.settings.veoShots = shots;
+    const close = whole("lipsyncShots", 0, 4);
+    if (close !== undefined) this.settings.lipsyncShots = close;
     const perDay = whole("albumsPerDay", 0, 24);
     if (perDay !== undefined) this.settings.albumsPerDay = perDay;
     if (input["newArtistChance"] !== undefined) {
@@ -1291,13 +1347,53 @@ export class AiLabel {
     } catch { /* the asked-for length */ }
     // Paid-for shots live beside the album until the video is cut, so nothing filmed is filmed twice.
     const shots = join(_album.folder, `.veo-${song.n}`);
-    const clips = await this.filmShots(artist, song, shots, scenes);
+    const { band: clips, singer } = await this.filmShots(artist, song, shots, scenes);
     if (clips.length < Math.max(2, Math.ceil(this.settings.veoShots / 2))) throw new Error(`only ${clips.length} of ${this.settings.veoShots} shots filmed so far`);
-    await (this.deps.filmedVideo ?? ((input) => renderFilmedVideo(this.deps.ffmpeg, input)))({ audio: song.file, clips, seconds, artist: artist.name, title: song.title, out });
+    const pinned = await this.syncCloseUps(song, singer, seconds, shots);
+    await (this.deps.filmedVideo ?? ((input) => renderFilmedVideo(this.deps.ffmpeg, input)))({ audio: song.file, clips, seconds, artist: artist.name, title: song.title, out, ...(pinned.length ? { pinned } : {}) });
     rmSync(shots, { recursive: true, force: true });
     return FILMED;
   }
 
+  /**
+   * The singer's close-ups, each placed on a sung line and its mouth redrawn
+   * to those seconds of the song. A close-up that cannot be synced is left
+   * out (the band fills its place): an unsynced singer is never shown.
+   */
+  private async syncCloseUps(song: LabelSong, singer: Array<{ path: string; seconds: number }>, seconds: number, keep: string): Promise<Array<{ path: string; at: number; seconds: number }>> {
+    const lipsync = this.deps.lipsync;
+    if (!lipsync || singer.length === 0) return [];
+    let lines: Array<{ start: number }> = [];
+    try { if (song.lrc) lines = parseLrc(readFileSync(song.lrc, "utf8")); } catch { /* the song's thirds instead */ }
+    const times = closeUpTimes(seconds, lines, singer.length);
+    const pinned: Array<{ path: string; at: number; seconds: number }> = [];
+    for (const [i, at] of times.entries()) {
+      const synced = join(keep, `synced-${i}-${Math.round(at * 100)}.mp4`);
+      try {
+        if (statSync(synced).size > 10_000) { pinned.push({ path: synced, at, seconds: 8 }); continue; }
+      } catch { /* not synced yet */ }
+      const shot = join(keep, `.send-${i}.mp4`);
+      const audio = join(keep, `.send-${i}.mp3`);
+      try {
+        // The shot made small enough to send (1080p, no sound) and the song's same 8 seconds.
+        await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-i", singer[i]!.path, "-an", "-c:v", "libx264", "-preset", "veryfast", "-crf", "21", "-t", "8", shot], 5 * 60_000, "the close-up did not shrink");
+        await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-ss", at.toFixed(2), "-t", "8", "-i", song.file, "-c:a", "libmp3lame", "-b:a", "192k", audio], 60_000, "the song's seconds did not cut");
+        const bytes = await lipsync({ video: readFileSync(shot), audio: readFileSync(audio), seconds: 8 });
+        writeFileSync(`${synced}.part`, bytes);
+        renameSync(`${synced}.part`, synced);
+        pinned.push({ path: synced, at, seconds: 8 });
+      } catch (error) {
+        this.log(`lip sync ${i + 1} for "${song.title}": ${(error as Error).message}; the band plays there instead`);
+        if (error instanceof VeoUnavailable) break;
+      } finally {
+        rmSync(shot, { force: true });
+        rmSync(audio, { force: true });
+      }
+    }
+    if (pinned.length) this.log(`lip-synced ${pinned.length} close-up(s) of "${song.title}"`);
+    return pinned;
+  }
+
   /** Whether this song gets filmed Veo shots: an album's single, Veo on, and the month's budget not spent. */
   private wantsVeo(song: Pick<LabelSong, "n">): boolean {
     return this.settings.veo && song.n === 1 && Boolean(this.deps.veo) && this.veoSpentIn !== new Date(this.now()).toISOString().slice(0, 7);
@@ -1308,9 +1404,9 @@ export class AiLabel {
    * Veo's reference images), on stage, in the song's mood. Stops for the
    * month when the budget is spent; a shot Veo will not make is skipped.
    */
-  private async filmShots(artist: LabelArtist, song: LabelSong, keep: string, dir: string): Promise<Array<{ path: string; seconds: number }>> {
+  private async filmShots(artist: LabelArtist, song: LabelSong, keep: string, dir: string): Promise<{ band: Array<{ path: string; seconds: number }>; singer: Array<{ path: string; seconds: number }> }> {
     const veo = this.deps.veo;
-    if (!veo) return [];
+    if (!veo) return { band: [], singer: [] };
     mkdirSync(dir, { recursive: true });
     mkdirSync(keep, { recursive: true });
     const members = this.cast(artist);
@@ -1326,11 +1422,16 @@ export class AiLabel {
         // A member without a portrait is described in words only.
       }
     }
-    const clips: Array<{ path: string; seconds: number }> = [];
-    for (const [i, prompt] of veoPrompts(artist, song, members, this.settings.veoShots).entries()) {
-      const file = join(keep, `shot-${i}.mp4`);
+    const band: Array<{ path: string; seconds: number }> = [];
+    const singer: Array<{ path: string; seconds: number }> = [];
+    // The singer's close-ups only where they can be lip-synced afterwards.
+    const plan = [
+      ...veoPrompts(artist, song, members, this.settings.veoShots).map((prompt, i) => ({ prompt, file: join(keep, `shot-${i}.mp4`), into: band })),
+      ...(this.deps.lipsync ? veoPrompts(artist, song, members, this.settings.lipsyncShots, "singer").map((prompt, i) => ({ prompt, file: join(keep, `singer-${i}.mp4`), into: singer })) : []),
+    ];
+    for (const [i, { prompt, file, into }] of plan.entries()) {
       try {
-        if (statSync(file).size > 10_000) { clips.push({ path: file, seconds: 8 }); continue; }
+        if (statSync(file).size > 10_000) { into.push({ path: file, seconds: 8 }); continue; }
       } catch { /* not filmed yet */ }
       try {
         // nixamp.com briefly away (a deploy: 502/503) or the network: twice more, a minute apart.
@@ -1344,7 +1445,7 @@ export class AiLabel {
         const partial = `${file}.part`;
         writeFileSync(partial, bytes!);
         renameSync(partial, file);
-        clips.push({ path: file, seconds: 8 });
+        into.push({ path: file, seconds: 8 });
       } catch (error) {
         if (error instanceof VeoUnavailable) {
           this.veoSpentIn = new Date(this.now()).toISOString().slice(0, 7);
@@ -1354,8 +1455,8 @@ export class AiLabel {
         this.log(`Veo shot ${i + 1} for "${song.title}": ${(error as Error).message}`);
       }
     }
-    if (clips.length) this.log(`Veo: ${clips.length} filmed shots for "${song.title}" (${artist.name})`);
-    return clips;
+    if (band.length || singer.length) this.log(`Veo: ${band.length + singer.length} filmed shots for "${song.title}" (${artist.name})`);
+    return { band, singer };
   }
 
   /** The label's music videos as one TV station: free to watch, with its breaks. */

package/src/discovery.ts

@@ -0,0 +1,210 @@
+/**
+ * How an agent, a store or a person finds every way into nixamp from nixamp.com
+ * alone: /llms.txt names the MCP servers, the API and the desktop downloads;
+ * /openapi.json describes the API; /api/v1/health says it is up; /download is
+ * the desktop app, and /download/<target> sends the browser straight to that
+ * installer on the latest release.
+ *
+ * Only nixamp.com answers these (the server where accounts live). A home
+ * server is somebody's own machine and has no business advertising itself.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export const RELEASES = "https://github.com/profullstack/nixamp/releases";
+const LATEST_API = "https://api.github.com/repos/profullstack/nixamp/releases/latest";
+
+/** Each installer release.yml builds, by the address /download/<target> gives it. */
+export const DESKTOP_TARGETS: ReadonlyArray<{ target: string; label: string; suffix: string }> = [
+  { target: "mac-arm64", label: "macOS (Apple silicon)", suffix: "-mac-arm64.dmg" },
+  { target: "mac-x64", label: "macOS (Intel)", suffix: "-mac-x64.dmg" },
+  { target: "win-x64", label: "Windows (x64)", suffix: "-win-x64.exe" },
+  { target: "win-arm64", label: "Windows (ARM)", suffix: "-win-arm64.exe" },
+  { target: "linux-x64", label: "Linux AppImage (x86_64)", suffix: "-linux-x86_64.AppImage" },
+  { target: "linux-arm64", label: "Linux AppImage (arm64)", suffix: "-linux-arm64.AppImage" },
+  { target: "deb-amd64", label: "Debian/Ubuntu .deb (amd64)", suffix: "-linux-amd64.deb" },
+  { target: "deb-arm64", label: "Debian/Ubuntu .deb (arm64)", suffix: "-linux-arm64.deb" },
+];
+
+export const DISCOVERY_PATHS = new Set(["/llms.txt", "/openapi.json", "/api/v1/health", "/download"]);
+export const isDiscoveryPath = (path: string): boolean => DISCOVERY_PATHS.has(path) || /^\/download\/[a-z0-9-]{1,20}$/.test(path);
+
+export interface ReleaseAsset { name: string; browser_download_url: string }
+export interface Release { tag_name: string; assets: ReleaseAsset[] }
+
+/** The installer for `target` among a release's files, or null when that build is missing. */
+export function desktopAsset(release: Release | null, target: string): string | null {
+  const spec = DESKTOP_TARGETS.find((one) => one.target === target);
+  if (!spec || !release) return null;
+  return release.assets.find((asset) => asset.name.startsWith("nixamp-") && asset.name.endsWith(spec.suffix))?.browser_download_url ?? null;
+}
+
+/**
+ * The latest published release, asked of GitHub at most every ten minutes. A
+ * failed ask keeps the last answer; with none, the downloads fall back to the
+ * releases page, which is never wrong, only one click longer.
+ */
+export function latestRelease(fetcher: typeof fetch = fetch, now: () => number = Date.now): () => Promise<Release | null> {
+  let kept: { at: number; release: Release | null } = { at: -Infinity, release: null };
+  return async () => {
+    if (now() - kept.at < 10 * 60_000) return kept.release;
+    try {
+      const response = await fetcher(LATEST_API, { headers: { accept: "application/vnd.github+json", "user-agent": "nixamp.com" }, signal: AbortSignal.timeout(8_000) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const body = await response.json() as Release;
+      kept = { at: now(), release: { tag_name: String(body.tag_name ?? ""), assets: Array.isArray(body.assets) ? body.assets : [] } };
+    } catch {
+      kept = { at: now(), release: kept.release };
+    }
+    return kept.release;
+  };
+}
+
+export function llmsTxt(site: string): string {
+  const desktop = DESKTOP_TARGETS.map((one) => `- ${one.label}: ${site}/download/${one.target}`).join("\n");
+  return `# nixamp
+
+> Broadcast live radio, television and film from your own machine. Open source streaming you run yourself: a terminal player, a web app (PWA) and a desktop app on one engine. Listen free, go live in one command, monetize with x402.
+
+## Web app (PWA)
+- ${site}/ : the player and remote, installable
+- ${site}/music : AI music, live and on demand, installable on its own
+
+## CLI
+- Install: curl -fsSL ${site}/install.sh | sh
+- Windows: irm ${site}/install.ps1 | iex
+- npm: npx -y nixamp
+
+## MCP
+- Public, no account (stations, what is on, share a track): ${site}/mcp/public
+- Signed in (watch parties, rooms, transcripts, music, your stations): ${site}/mcp , a nixamp token as the bearer (\`nixamp token create\`) or OAuth
+- Local over stdio: npx -y nixamp mcp
+
+## API
+- OpenAPI: ${site}/openapi.json
+- Base: ${site}/api/v1
+- GET /api/v1/health
+- GET /api/v1/music : the AI label's catalogue, every genre station, artist and album
+- GET /api/v1/stations : public stations
+- GET /api/v1/guide/rooms : live rooms
+- GET /api/v1/guide/vods : films and shows on demand
+- GET /api/directory : every nixamp server that is broadcasting
+- GET /api/v1/auth/me : who the bearer token is
+- POST /api/v1/auth/device/code : sign a CLI or agent in from a browser
+
+## Desktop app
+Downloads: ${site}/download
+${desktop}
+Every release: ${RELEASES}
+`;
+}
+
+const ok = { description: "OK", content: { "application/json": { schema: { type: "object" } } } };
+const signedIn = { description: "Not signed in", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } };
+const route = (summary: string, tags: string[], auth = false) => ({
+  summary,
+  tags,
+  ...(auth ? { security: [{ bearer: [] }], responses: { 200: ok, 401: signedIn } } : { responses: { 200: ok } }),
+});
+
+/** The API as OpenAPI 3.1: what an agent can call on nixamp.com, and which calls want a token. */
+export function openapiDocument(site: string, version: string): Record<string, unknown> {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "nixamp",
+      version,
+      description: "Live radio, television and film from your own machine. Public routes answer anybody; the rest want a nixamp token as the bearer (`nixamp token create`).",
+      license: { name: "MIT", identifier: "MIT" },
+    },
+    servers: [{ url: site }],
+    externalDocs: { description: "llms.txt: MCP, CLI, desktop and API in one place", url: `${site}/llms.txt` },
+    components: {
+      securitySchemes: { bearer: { type: "http", scheme: "bearer", description: "A nixamp token (`nixamp token create`) or an OAuth access token." } },
+      schemas: { Error: { type: "object", properties: { error: { type: "string" } }, required: ["error"] } },
+    },
+    paths: {
+      "/api/v1/health": { get: route("Is nixamp.com up, and which version", ["meta"]) },
+      "/api/directory": { get: route("Every nixamp server that is broadcasting", ["stations"]) },
+      "/api/v1/stations": { get: route("Public stations", ["stations"]) },
+      "/api/v1/guide/rooms": { get: route("Live rooms on the guide", ["stations"]) },
+      "/api/v1/guide/vods": { get: route("Films and shows on demand", ["stations"]) },
+      "/api/v1/opendirs": { get: route("Open directories nixamp has indexed", ["stations"]) },
+      "/api/v1/music": { get: route("The AI label's catalogue: genre stations, artists, albums", ["music"]) },
+      "/api/v1/auth/providers": { get: route("How you can sign in", ["auth"]) },
+      "/api/v1/auth/device/code": { post: route("Start a device sign-in (CLI or agent); a person approves it in a browser", ["auth"]) },
+      "/api/v1/auth/device/token": { post: route("Collect the token once the device sign-in is approved", ["auth"]) },
+      "/api/v1/auth/me": { get: route("Who the bearer is", ["auth"], true) },
+      "/api/v1/auth/tokens": { get: route("Your tokens", ["auth"], true), post: route("Make a token", ["auth"], true) },
+      "/api/v1/follows": { get: route("Who you follow", ["social"], true) },
+      "/api/v1/favorites": { get: route("Your favourite stations", ["social"], true) },
+      "/api/v1/servers": { get: route("Your nixamp servers", ["servers"], true) },
+      "/mcp/public": { post: route("MCP (streamable HTTP, JSON-RPC): the public station tools", ["mcp"]) },
+      "/mcp": { post: route("MCP (streamable HTTP, JSON-RPC): every tool, as the bearer", ["mcp"], true) },
+    },
+  };
+}
+
+const escape = (text: string): string => text.replace(/[&<>"']/g, (one) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[one]!);
+
+const STYLE = "body{margin:0;background:#080c09;color:#d8e6da;font:16px/1.5 system-ui,sans-serif}main{max-width:640px;margin:0 auto;padding:32px 16px}h1{font-size:28px;margin:0 0 4px}a{color:#7ee787}ul{padding:0;list-style:none}li{margin:10px 0}li a{display:block;padding:12px 14px;border:1px solid #1f2b22;border-radius:8px;text-decoration:none}li a:hover{border-color:#7ee787}code{background:#111a13;padding:2px 6px;border-radius:4px}.by{color:#8aa08e;margin:0 0 24px}";
+
+export function downloadPage(site: string, release: Release | null): string {
+  const tag = release?.tag_name ? ` ${escape(release.tag_name)}` : "";
+  const items = DESKTOP_TARGETS.map((one) => `<li><a href="/download/${one.target}">${escape(one.label)}</a></li>`).join("");
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Download the desktop app · nixamp</title><meta name="description" content="nixamp for macOS, Windows and Linux: the player, the radio console and a nixamp server in one app.">
+<link rel="canonical" href="${escape(site)}/download"><link rel="icon" href="/favicon.png" type="image/png"><style>${STYLE}</style></head>
+<body><main><h1>nixamp for your desktop</h1><p class="by">The player, the radio console and a nixamp server in one app${tag}.</p>
+<ul>${items}</ul>
+<p>Or in a terminal: <code>curl -fsSL ${escape(site)}/install.sh | sh</code></p>
+<p><a href="/">Open the web app</a> · <a href="${RELEASES}">Every release</a> · <a href="/llms.txt">For agents</a></p></main></body></html>`;
+}
+
+export interface DiscoveryContext {
+  site: string;
+  version: string;
+  release: () => Promise<Release | null>;
+  json: (response: ServerResponse, code: number, body: unknown) => void;
+}
+
+function send(response: ServerResponse, code: number, type: string, body: string, method: string, extra: Record<string, string> = {}): void {
+  response.writeHead(code, { "content-type": type, "content-length": Buffer.byteLength(body), "cache-control": "public, max-age=300", "access-control-allow-origin": "*", ...extra });
+  response.end(method === "HEAD" ? undefined : body);
+}
+
+/** Answers a discovery path; false when `path` is not one, so the caller carries on. */
+export async function handleDiscovery(request: IncomingMessage, response: ServerResponse, path: string, ctx: DiscoveryContext): Promise<boolean> {
+  if (!isDiscoveryPath(path)) return false;
+  const method = request.method ?? "GET";
+  if (method !== "GET" && method !== "HEAD") {
+    response.writeHead(405, { allow: "GET, HEAD" });
+    response.end();
+    return true;
+  }
+  const site = ctx.site.replace(/\/+$/, "");
+  if (path === "/api/v1/health") {
+    ctx.json(response, 200, { ok: true, name: "nixamp", version: ctx.version });
+    return true;
+  }
+  if (path === "/llms.txt") {
+    send(response, 200, "text/plain; charset=utf-8", llmsTxt(site), method);
+    return true;
+  }
+  if (path === "/openapi.json") {
+    send(response, 200, "application/json; charset=utf-8", JSON.stringify(openapiDocument(site, ctx.version), null, 2), method);
+    return true;
+  }
+  if (path === "/download") {
+    send(response, 200, "text/html; charset=utf-8", downloadPage(site, await ctx.release()), method, { "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; img-src 'self'; base-uri 'none'; frame-ancestors 'none'` });
+    return true;
+  }
+  const target = path.slice("/download/".length);
+  if (!DESKTOP_TARGETS.some((one) => one.target === target)) {
+    ctx.json(response, 404, { error: `no such download; one of ${DESKTOP_TARGETS.map((one) => one.target).join(", ")}` });
+    return true;
+  }
+  // Short-lived: the next release moves it.
+  response.writeHead(302, { location: desktopAsset(await ctx.release(), target) ?? `${RELEASES}/latest`, "cache-control": "public, max-age=300" });
+  response.end();
+  return true;
+}

package/src/server.ts

@@ -152,6 +152,7 @@ import {
 } from "./transcripts.ts";
 import { handleMessage as mcpMessage } from "./mcp.ts";
 import { PUBLIC_TOOLS, callPublicTool, isPublicTool } from "./directory-mcp.ts";
+import { handleDiscovery, isDiscoveryPath, latestRelease } from "./discovery.ts";
 import { Media, factsFromRequest, holderFrom, mediaId, openFileListing, openFileOf, type MediaRecord } from "./media.ts";
 import { mediaPage, type PageTranscript } from "./media-page.ts";
 import { describeFile, refreshChanged } from "./media-local.ts";
@@ -350,7 +351,8 @@ export function parseServeArgs(argv: string[]): ServeOptions {
     tlsCert: process.env["NIXAMP_TLS_CERT"] ?? "",
     tlsKey: process.env["NIXAMP_TLS_KEY"] ?? "",
     x402: false,
-    owner: "",
+    // The account that administers this server, for one with no key but accounts (nixamp.com).
+    owner: process.env["NIXAMP_OWNER"] ?? "",
     ingest: false,
     rtmpIn: 0,
     rtmpStreams: 3,
@@ -2030,6 +2032,12 @@ export interface HandlerOptions {
 export function createHandler(engine: Engine, options: HandlerOptions) {
   // One per server, so the counters survive between requests and die with it.
   const guard = new Guard();
+  // --no-key opens a server to whoever reaches it, unless it has an owner: then
+  // anyone may listen and only the owner (or the control key) administers.
+  // nixamp.com is that server; without this every visitor was its admin.
+  const openToAll = (key: string | null): boolean => key === null && !options.owner?.claimed;
+  // nixamp.com's /download asks GitHub which release is latest; one answer per ten minutes.
+  const release = latestRelease();
 
   const tracker = options.connections ?? new Connections();
   const started = Date.now();
@@ -2187,7 +2195,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
             cors: CORS,
             watch: (incoming, outgoing, track) => watch(incoming, outgoing, "stream", track),
             controls: async () => {
-              if (key === null) return true;
+              if (openToAll(key)) return true;
               if (scopeOf(keyFrom(request, url), key, null) === "control") return true;
               if (options.owner) return (await options.owner.check(false, tokenFrom(request.headers))).allowed;
               return false;
@@ -2873,6 +2881,8 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       !(/^\/radio\/(artist|album)\//.test(path) && Boolean(options.music)) &&
       // What is on, as MCP, for anybody.
       path !== "/mcp/public" &&
+      // llms.txt, the OpenAPI document, the health check and the desktop downloads (nixamp.com).
+      !(isDiscoveryPath(path) && Boolean(options.accounts && options.site)) &&
       // Supporting a copyright holder is for anybody listening.
       !/^\/support\/[a-z0-9-]{1,40}$/.test(path) && path !== "/support/cancel" && !/^\/api\/v1\/support\/[a-z0-9-]{1,40}$/.test(path) &&
       // A station's short link, which sends the browser to wherever it plays.
@@ -2935,7 +2945,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
     // or the owner's nixamp.com session. Asked by the routes that do not go
     // through the admin gate further down.
     const controlOf = async (): Promise<{ allowed: boolean; account: string }> => {
-      if (key === null) return { allowed: true, account: "" };
+      if (openToAll(key)) return { allowed: true, account: "" };
       if (scopeOf(keyFrom(request, url), key, listenKey) === "control") return { allowed: true, account: "" };
       if (options.owner) {
         const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
@@ -3556,6 +3566,9 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       return;
     }
 
+    // Every way into nixamp, for agents and stores: llms.txt, OpenAPI, health, desktop downloads (discovery.ts).
+    if (options.accounts && options.site && await handleDiscovery(request, response, path, { site: options.site, version: options.version, release, json })) return;
+
     if (path === "/reset-password" && options.accounts?.passwordResets) {
       if (request.method !== "GET" && request.method !== "HEAD") {
         json(response, 405, { error: "GET only" }); return;
@@ -5231,11 +5244,11 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       eventChannelRequest,
     );
     if (options.owner && needsAdmin(path, request.method ?? "GET") && !eventMediaOperation) {
-      // A server started with --no-key has said that anyone who can reach the
-      // port may drive it, and prints exactly that. Locking administration to
-      // nobody would contradict it and leave such a server unadministrable.
+      // A server started with --no-key and no owner has said that anyone who
+      // can reach the port may drive it, and prints exactly that. With an owner
+      // (nixamp.com), --no-key only means anyone may listen: the owner drives.
       const holdsControl =
-        key === null || scopeOf(keyFrom(request, url), key, null) === "control";
+        openToAll(key) || scopeOf(keyFrom(request, url), key, null) === "control";
       // A session in the query as well as in a header or a cookie: from
       // nixamp.com's page a server is another origin, and the cookie stays
       // home, so the session travels the way the key does.
@@ -5393,7 +5406,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       if (path === "/api/catalogs" && request.method === "GET") {
         // Where a list is read from is the administrator's business, not a
         // listener's: it can carry a provider's credentials in the URL.
-        const holdsControl = key === null || scopeOf(keyFrom(request, url), key, null) === "control";
+        const holdsControl = openToAll(key) || scopeOf(keyFrom(request, url), key, null) === "control";
         const admin = options.owner
           ? (await options.owner.check(holdsControl, tokenFrom(request.headers))).allowed
           : holdsControl;
@@ -7728,6 +7741,21 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
       if (!answer.ok) throw new Error(((await answer.json().catch(() => ({}))) as { error?: string }).error ?? `nixamp.com answered ${answer.status}`);
       return Buffer.from(await answer.arrayBuffer());
     },
+    // A singer's close-up redrawn to the song's own seconds, by nixamp.com (fal.ai), under the same cap.
+    lipsync: async (input) => {
+      const session = readSession();
+      const here = stations.publicBase?.() ?? "";
+      if (!session?.token || !/^https:\/\//.test(here)) throw new VeoUnavailable("this server is not signed in to nixamp.com");
+      const answer = await fetch(`${session.site.replace(/\/+$/, "")}/api/v1/music/veo`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${session.token}`, "x-nixamp-server": here },
+        body: JSON.stringify({ lipsync: true, seconds: input.seconds, video: input.video.toString("base64"), audio: input.audio.toString("base64") }),
+        signal: AbortSignal.timeout(15 * 60_000),
+      });
+      if (answer.status === 402) throw new VeoUnavailable(((await answer.json().catch(() => ({}))) as { error?: string }).error ?? `HTTP ${answer.status}`);
+      if (!answer.ok) throw new Error(((await answer.json().catch(() => ({}))) as { error?: string }).error ?? `nixamp.com answered ${answer.status}`);
+      return Buffer.from(await answer.arrayBuffer());
+    },
     // A release is told to nixamp.com as this server's owner; nixamp.com tells the artist's followers.
     announce: (release) => {
       const session = readSession();
@@ -8029,6 +8057,8 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     ledger: pool ? pgLedger(pool as unknown as import("./veo-studio.ts").Queryable) : fileLedger(VeoStudio.fileFor(stateDir(), options.port)),
     monthlyUsd: Number(process.env["NIXAMP_VEO_MONTHLY_USD"] ?? 50),
     usdPerSecond: Number(process.env["NIXAMP_VEO_USD_PER_SECOND"] ?? 0.15),
+    ...(process.env["FAL_KEY"] ? { falKey: process.env["FAL_KEY"] } : {}),
+    lipsyncUsdPerSecond: Number(process.env["NIXAMP_LIPSYNC_USD_PER_SECOND"] ?? 0.1),
   }) : undefined;
   /** The signed-in account owns a server listed in the directory at this base. */
   const ownsListed = async (request: IncomingMessage, base: string): Promise<boolean> => {
@@ -8045,8 +8075,21 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     if (!(await ownsListed(request, base))) return { status: 403, body: { error: "only the owner of a listed server" } };
     if (request.method === "GET") return { status: 200, body: await veoStudio.status() };
     if (request.method !== "POST") return { status: 405, body: { error: "GET or POST" } };
-    let input: { prompt?: unknown; seconds?: unknown; references?: unknown };
-    try { input = JSON.parse(await readBody(request, 2 * 1024 * 1024)) as typeof input; } catch { return { status: 400, body: { error: "a JSON body under 2 MB" } }; }
+    let input: { prompt?: unknown; seconds?: unknown; references?: unknown; lipsync?: unknown; video?: unknown; audio?: unknown };
+    // A lip sync carries an 8 s 1080p shot and its seconds of the song: up to 48 MB as base64.
+    try { input = JSON.parse(await readBody(request, 48 * 1024 * 1024)) as typeof input; } catch { return { status: 400, body: { error: "a JSON body under 48 MB" } }; }
+    if (input.lipsync === true) {
+      if (!veoStudio.canLipsync) return { status: 404, body: { error: "lip sync is not set up here" } };
+      const video = Buffer.from(String(input.video ?? ""), "base64");
+      const audio = Buffer.from(String(input.audio ?? ""), "base64");
+      if (video.length < 10_000 || audio.length < 1_000) return { status: 400, body: { error: "a shot and its audio" } };
+      try {
+        return { status: 200, body: null, video: await veoStudio.lipsync({ video, audio, seconds: Number(input.seconds ?? 8) }) };
+      } catch (error) {
+        if (error instanceof VeoBudgetError) return { status: 402, body: { error: error.message, code: "budget", ...(await veoStudio.status()) } };
+        return { status: 422, body: { error: (error as Error).message, code: "refused" } };
+      }
+    }
     const prompt = String(input.prompt ?? "").trim();
     if (prompt.length < 20) return { status: 400, body: { error: "describe the shot" } };
     const references = (Array.isArray(input.references) ? input.references : []).slice(0, 3).map((one) => Buffer.from(String(one), "base64")).filter((one) => one.length > 1000);
@@ -8884,7 +8927,9 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   }
 
   console.log("");
-  if (key === null) {
+  if (key === null && owner.claimed) {
+    console.log("  No key: anyone who can reach this port can hear it; only its owner can drive it.");
+  } else if (key === null) {
     console.log("  No key: anyone who can reach this port can drive it and hear it.");
   } else {
     console.log("  Open that link once on a phone or a laptop and it stays signed in.");

package/src/station-cli.ts

@@ -506,6 +506,7 @@ async function labelCommand(argv: string[], call: Call, show: Show): Promise<num
         resetDay: number("--reset-day"),
         veo: has(argv, "--veo") ? true : has(argv, "--no-veo") ? false : undefined,
         veoShots: number("--veo-shots"),
+        lipsyncShots: number("--lipsync-shots"),
         genreOrder: flag(argv, "--genres"),
         enabled: has(argv, "--off") ? false : has(argv, "--on") ? true : undefined,
         publish: has(argv, "--unlisted") ? false : has(argv, "--public") ? true : undefined,