From c4bf2b188b0b9536eb165f4da889cc2e495d7983 Mon Sep 17 00:00:00 2001 From: Robert Wagner Date: Mon, 16 Nov 2026 09:52:06 -0500 Subject: [PATCH 1/3] Read episode video and timed transcript lines from the feed - feed-media: scan the raw feed XML for video, which rss-to-json drops, and attach it to each episode. - cues: timed transcript lines from the feed's transcript (VTT/JSON/SRT) or a markdown transcript, served at /api/cues/[episode].json. - cast: sort an episode's hosts and guests and match them to transcript voices. Co-Authored-By: Claude Opus 5.5 --- packages/starpod/src/lib/cast.ts | 85 +++++++ packages/starpod/src/lib/cues.ts | 211 ++++++++++++++++++ packages/starpod/src/lib/episode-cues.ts | 28 +++ packages/starpod/src/lib/feed-media.ts | 86 +++++++ packages/starpod/src/lib/rss.ts | 14 +- packages/starpod/src/lib/transcript.ts | 4 +- .../src/pages/api/cues/[episode].json.ts | 23 ++ tests/unit/cast.test.ts | 67 ++++++ tests/unit/cues.test.ts | 55 +++++ tests/unit/feed-media.test.ts | 47 ++++ 10 files changed, 617 insertions(+), 3 deletions(-) create mode 100644 packages/starpod/src/lib/cast.ts create mode 100644 packages/starpod/src/lib/cues.ts create mode 100644 packages/starpod/src/lib/episode-cues.ts create mode 100644 packages/starpod/src/lib/feed-media.ts create mode 100644 packages/starpod/src/pages/api/cues/[episode].json.ts create mode 100644 tests/unit/cast.test.ts create mode 100644 tests/unit/cues.test.ts create mode 100644 tests/unit/feed-media.test.ts diff --git a/packages/starpod/src/lib/cast.ts b/packages/starpod/src/lib/cast.ts new file mode 100644 index 0000000..4098189 --- /dev/null +++ b/packages/starpod/src/lib/cast.ts @@ -0,0 +1,85 @@ +import type { TranscriptCue } from './cues'; + +/** A person on an episode, as recorded in the guests/sponsors database. */ +export interface CastPerson { + id: string; + img: string | null; + isHost: boolean; + name: string; +} + +/** + * The episode's people in credit order: this episode's hosts first (the + * show's configured hosts in config order, then guest hosts alphabetically), + * then guests alphabetically. Whether someone hosted is the episode's own + * record (`isHost`), so a regular host who joined one episode as a guest is + * credited as a guest there. + */ +export function sortCast( + people: Array, + configuredHosts: Array +): Array { + return [...people].sort((a, b) => { + if (a.isHost !== b.isHost) { + return a.isHost ? -1 : 1; + } + if (!a.isHost) { + return a.name.localeCompare(b.name); + } + const aIndex = configuredHosts.indexOf(a.name); + const bIndex = configuredHosts.indexOf(b.name); + if (aIndex !== -1 && bIndex !== -1) { + return aIndex - bIndex; + } + if (aIndex !== -1) { + return -1; + } + if (bIndex !== -1) { + return 1; + } + return a.name.localeCompare(b.name); + }); +} + +const tokens = (name: string) => + name + .toLowerCase() + .split(/[\s.]+/) + .map((token) => token.replace(/[^a-z0-9]/g, '')) + .filter(Boolean); + +/** + * Do these two names refer to the same person? Loosely: their first names + * start the same way ("Robbie" ~ "RobbieTheWagner"), or they share a surname + * ("Chuck Carpenter" ~ "Charles William Carpenter III"). + */ +function sameName(a: string, b: string) { + const [aFirst = '', ...aRest] = tokens(a); + const [bFirst = '', ...bRest] = tokens(b); + if (aFirst.length >= 3 && bFirst.length >= 3 && (aFirst.startsWith(bFirst) || bFirst.startsWith(aFirst))) { + return true; + } + return aRest.some((token) => token.length >= 4 && bRest.includes(token)); +} + +/** + * Which transcript voice (0 or 1, the two most talkative speakers) a person + * speaks in, so their name on the stage wears the same typeface as their + * lines. People who don't speak as one of those two, or can't be matched, get + * no voice. + */ +export function voiceFor( + name: string, + cues: Array | null +): number | undefined { + if (!cues?.length) { + return undefined; + } + for (const voice of [0, 1]) { + const speaker = cues.find((cue) => cue.v === voice && cue.n)?.n; + if (speaker && sameName(name, speaker)) { + return voice; + } + } + return undefined; +} diff --git a/packages/starpod/src/lib/cues.ts b/packages/starpod/src/lib/cues.ts new file mode 100644 index 0000000..35837ed --- /dev/null +++ b/packages/starpod/src/lib/cues.ts @@ -0,0 +1,211 @@ +import type { Episode } from './rss'; +import { parseCues } from './transcript'; + +/** + * A short, timed line of speech for the live transcript performance. `v` is + * the voice: the speaker's order of first appearance (0, 1, 2…), absent when + * the source carries no speaker names (plain captions). `n` is the name. + */ +export interface TranscriptCue { + s: number; + t: string; + v?: number; + n?: string; +} + +interface Segment { + start: number; + text: string; + speaker?: string; +} + +// Lines longer than this are split at sentence ends so the live line stays a +// phrase, not a paragraph. +const CUE_TARGET_CHARS = 140; + +export function mergeIntoLines(segments: Array): Array { + const voices = new Map(); + const lines: Array = []; + let current: TranscriptCue | null = null; + let speaker: string | undefined; + + for (const segment of segments) { + const endsSentence = current ? /[.!?]["”’)]?$/.test(current.t) : false; + // Never break mid-sentence unless a line runs far past the target; a + // transcript paragraph that was cut mid-thought joins the next one. + const startNew = + !current || + segment.speaker !== speaker || + (current.t.length >= CUE_TARGET_CHARS / 2 && endsSentence) || + current.t.length >= CUE_TARGET_CHARS * 1.6; + + if (startNew) { + speaker = segment.speaker; + current = { s: Math.round(segment.start * 10) / 10, t: segment.text }; + if (speaker) { + if (!voices.has(speaker)) { + voices.set(speaker, voices.size); + } + current.v = voices.get(speaker); + current.n = speaker; + } + lines.push(current); + } else if (current) { + current.t = `${current.t} ${segment.text}`; + } + } + + return rankVoices(lines); +} + +/** + * The two people who talk the most get the two signature voices (0 and 1, in + * order of first appearance); everyone else (intros, guests, ads) shares the + * supporting voices from 2 up. + */ +function rankVoices(lines: Array): Array { + const counts = new Map(); + const firstSeen: Array = []; + for (const line of lines) { + if (!line.n) { + continue; + } + if (!counts.has(line.n)) { + firstSeen.push(line.n); + } + counts.set(line.n, (counts.get(line.n) ?? 0) + 1); + } + const leads = [...counts.entries()] + .sort((a, b) => b[1] - a[1]) + .slice(0, 2) + .map(([name]) => name) + .sort((a, b) => firstSeen.indexOf(a) - firstSeen.indexOf(b)); + const supporting = firstSeen.filter((name) => !leads.includes(name)); + for (const line of lines) { + if (line.n) { + const lead = leads.indexOf(line.n); + line.v = lead !== -1 ? lead : 2 + (supporting.indexOf(line.n) % 4); + } + } + return lines; +} + +const MARKDOWN_LINE = + /^\s*\[(?:(\d+):)?(\d{1,2}):(\d{2})\]\s*(?:(?:\*\*|__)?([^:\n[\]*_]{1,40}):(?:\*\*|__)?\s*)?(.*)$/; + +function stripInlineMarkdown(text: string): string { + return text + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/(\*\*|__|\*|_|`)/g, ''); +} + +/** + * Parse a markdown transcript (`[HH:MM:SS] Speaker: text` paragraphs) into + * timed lines with voices. Long speeches split into sentences that share the + * paragraph's start time, so they still perform one phrase at a time. + */ +export function parseMarkdownCues(markdown: string): Array { + const paragraphs: Array<{ start: number; speaker?: string; sentences: Array }> = []; + for (const block of markdown.split(/\n{2,}/)) { + const match = block.replace(/\n/g, ' ').match(MARKDOWN_LINE); + if (!match) { + continue; + } + const [, h, m, sec, name, text] = match; + const sentences = ( + stripInlineMarkdown(text).trim().match(/[^.!?]+[.!?]+["”’)]?|[^.!?]+$/g) ?? [] + ) + .map((sentence) => sentence.trim()) + .filter(Boolean); + paragraphs.push({ + start: Number(h ?? 0) * 3600 + Number(m) * 60 + Number(sec), + speaker: name?.trim(), + sentences + }); + } + + // Each sentence starts partway through its paragraph, in proportion to the + // text before it, so the live line moves at roughly the pace of speech. + const segments: Array = []; + paragraphs.forEach((paragraph, index) => { + const total = paragraph.sentences.reduce((sum, item) => sum + item.length, 0) || 1; + const next = paragraphs[index + 1]?.start; + const span = next && next > paragraph.start ? next - paragraph.start : total / 15; + let offset = 0; + for (const sentence of paragraph.sentences) { + segments.push({ + start: paragraph.start + (span * offset) / total, + text: sentence, + speaker: paragraph.speaker + }); + offset += sentence.length; + } + }); + return mergeIntoLines(segments); +} + +/** + * Timed lines from the feed's `` (VTT/SRT cues or JSON + * segments). Returns `null` when none is available. + */ +const rssCueCache = new Map | null>>(); + +export function getRssCues( + episode: Episode +): Promise | null> { + const url = episode.transcriptUrl; + if (!url) { + return Promise.resolve(null); + } + let pending = rssCueCache.get(url); + if (!pending) { + pending = fetchRssCues(episode, url); + rssCueCache.set(url, pending); + } + return pending; +} + +async function fetchRssCues( + episode: Episode, + url: string +): Promise | null> { + try { + const response = await fetch(url); + if (!response.ok) { + return null; + } + const raw = await response.text(); + const type = ( + episode.transcriptType || + response.headers.get('content-type') || + '' + ).toLowerCase(); + + if (type.includes('json')) { + const data = JSON.parse(raw) as { + segments?: Array<{ text?: string; start?: number; speaker?: string }>; + }; + const segments = (data.segments ?? []) + .filter((s) => s.text?.trim() && typeof s.start === 'number') + .map((s) => ({ + start: s.start!, + text: s.text!.trim(), + speaker: s.speaker || undefined + })); + return segments.length ? mergeIntoLines(segments) : null; + } + + const cues = parseCues(raw).map((cue) => { + // WebVTT voice spans: text + const voice = cue.text.match(/^]*)?\s+([^>]+)>/); + return { + start: cue.start, + text: cue.text.replace(/<[^>]+>/g, '').trim(), + speaker: voice?.[1]?.trim() + }; + }); + return cues.length ? mergeIntoLines(cues) : null; + } catch { + return null; + } +} diff --git a/packages/starpod/src/lib/episode-cues.ts b/packages/starpod/src/lib/episode-cues.ts new file mode 100644 index 0000000..a2f5a6e --- /dev/null +++ b/packages/starpod/src/lib/episode-cues.ts @@ -0,0 +1,28 @@ +import { getEntry } from 'astro:content'; + +import { getRssCues, parseMarkdownCues, type TranscriptCue } from './cues'; +import type { Episode } from './rss'; + +/** + * Timed lines for an episode: a markdown transcript in the site's content + * collection wins (it names speakers), then the feed's transcript. Server-only. + */ +export async function getEpisodeCues( + episode: Episode +): Promise | null> { + if (episode.episodeNumber && episode.episodeNumber !== 'Bonus') { + let entry; + try { + entry = await getEntry('transcripts', episode.episodeNumber); + } catch { + entry = undefined; + } + if (entry?.body) { + const cues = parseMarkdownCues(entry.body); + if (cues.length) { + return cues; + } + } + } + return getRssCues(episode); +} diff --git a/packages/starpod/src/lib/feed-media.ts b/packages/starpod/src/lib/feed-media.ts new file mode 100644 index 0000000..45ef606 --- /dev/null +++ b/packages/starpod/src/lib/feed-media.ts @@ -0,0 +1,86 @@ +/** + * Video discovery for feed items. + * + * `rss-to-json` drops nested Podcasting 2.0 elements such as + * ``, so the raw feed XML is scanned here instead. + * An item's video is its first alternate enclosure whose type is video or an + * HLS playlist; the `` inside it is the stream URL. + */ + +export interface FeedVideo { + src: string; + type: string; +} + +const HLS_TYPES = ['application/x-mpegurl', 'application/vnd.apple.mpegurl']; + +function decodeEntities(value: string): string { + return value + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, "'"); +} + +function attribute(tag: string, name: string): string | undefined { + const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`, 'i')); + return match ? decodeEntities(match[1]) : undefined; +} + +export function isVideoType(type: string): boolean { + const lower = type.toLowerCase(); + return lower.startsWith('video/') || HLS_TYPES.includes(lower); +} + +/** + * Map each item's guid to its video, for items that carry one. + */ +export function extractVideosByGuid(xml: string): Map { + const videos = new Map(); + + for (const item of xml.split(/]/i).slice(1)) { + const body = item.split(/<\/item>/i)[0]; + const guid = body.match(/]*>([\s\S]*?)<\/guid>/i)?.[1]; + if (!guid) { + continue; + } + + const enclosures = body.match( + //gi + ); + for (const enclosure of enclosures ?? []) { + const openTag = enclosure.match(/]*>/i)![0]; + const type = attribute(openTag, 'type') ?? ''; + if (!isVideoType(type)) { + continue; + } + const sourceTag = enclosure.match(/]*>/i)?.[0]; + const src = sourceTag && attribute(sourceTag, 'uri'); + if (src) { + videos.set(decodeEntities(guid.trim()), { src, type }); + break; + } + } + } + + return videos; +} + +/** + * Fetch the feed and extract its videos. A failure here must never break the + * build: the site simply falls back to audio-first everywhere. + */ +export async function fetchFeedVideos( + feedUrl: string +): Promise> { + try { + const response = await fetch(feedUrl); + if (!response.ok) { + return new Map(); + } + return extractVideosByGuid(await response.text()); + } catch { + return new Map(); + } +} diff --git a/packages/starpod/src/lib/rss.ts b/packages/starpod/src/lib/rss.ts index 91670ce..ddeb1b1 100644 --- a/packages/starpod/src/lib/rss.ts +++ b/packages/starpod/src/lib/rss.ts @@ -10,6 +10,7 @@ import { union } from 'valibot'; +import { fetchFeedVideos, type FeedVideo } from './feed-media'; import { optimizeImage } from './optimize-episode-image'; import type { StarpodConfig } from '../utils/config'; import { dasherize } from '../utils/dasherize'; @@ -60,6 +61,10 @@ export interface Episode { src: string; type: string; }; + // The episode's video stream, from a `` with a + // video or HLS type. When present the site leads with video and offers a + // switch to audio. + video?: FeedVideo; // A transcript referenced by the feed's `` tag, if any. // Used as a fallback when no explicit markdown transcript is provided for the // episode. @@ -146,7 +151,11 @@ export async function getAllEpisodes(config?: StarpodConfig) { ) }); - let feed = (await parseRssFeed(await resolveRssFeed(config))) as Show; + const feedUrl = await resolveRssFeed(config); + const [feed, videos] = await Promise.all([ + parseRssFeed(feedUrl) as Promise, + fetchFeedVideos(feedUrl) + ]); let items = parse(FeedSchema, feed).items; let episodes: Array = await Promise.all( @@ -192,7 +201,8 @@ export async function getAllEpisodes(config?: StarpodConfig) { audio: { src: audioEnclosure.url, type: audioEnclosure.type ?? 'audio/mpeg' - } + }, + video: videos.get(id) }; } ) diff --git a/packages/starpod/src/lib/transcript.ts b/packages/starpod/src/lib/transcript.ts index ce3d36f..d6706c1 100644 --- a/packages/starpod/src/lib/transcript.ts +++ b/packages/starpod/src/lib/transcript.ts @@ -124,7 +124,9 @@ function parseTranscript( * start time (in seconds) of each cue. Blocks without a `-->` timing line * (e.g. the `WEBVTT` header) are skipped. */ -function parseCues(raw: string): Array<{ text: string; start: number }> { +export function parseCues( + raw: string +): Array<{ text: string; start: number }> { const cues: Array<{ text: string; start: number }> = []; for (const block of raw.replace(/\r\n/g, '\n').split(/\n{2,}/)) { diff --git a/packages/starpod/src/pages/api/cues/[episode].json.ts b/packages/starpod/src/pages/api/cues/[episode].json.ts new file mode 100644 index 0000000..1ccac23 --- /dev/null +++ b/packages/starpod/src/pages/api/cues/[episode].json.ts @@ -0,0 +1,23 @@ +import type { APIRoute, GetStaticPaths } from 'astro'; + +import { getEpisodeCues } from '../../../lib/episode-cues'; +import { getAllEpisodes, type Episode } from '../../../lib/rss'; + +/** + * Timed transcript lines for one episode, fetched lazily by the stage's + * live transcript. Episodes without a transcript return an empty list. + */ +export const getStaticPaths: GetStaticPaths = async () => { + const episodes = await getAllEpisodes(); + return episodes.map((episode) => ({ + params: { episode: episode.episodeSlug }, + props: { episode } + })); +}; + +export const GET: APIRoute = async ({ props }) => { + const cues = await getEpisodeCues(props.episode as Episode); + return new Response(JSON.stringify(cues ?? []), { + headers: { 'Content-Type': 'application/json; charset=utf-8' } + }); +}; diff --git a/tests/unit/cast.test.ts b/tests/unit/cast.test.ts new file mode 100644 index 0000000..e516cb7 --- /dev/null +++ b/tests/unit/cast.test.ts @@ -0,0 +1,67 @@ +import { describe, expect, it } from 'vitest'; +import { sortCast, voiceFor } from 'starpod/src/lib/cast'; + +const person = (name: string, isHost: boolean) => ({ id: name, img: null, isHost, name }); + +describe('sortCast', () => { + const hosts = ['RobbieTheWagner', 'Chuck Carpenter', 'Adam Argyle']; + + it('credits this episode’s hosts first (configured order, then guest hosts), then guests', () => { + const sorted = sortCast( + [ + person('Zed Guest', false), + person('Adam Argyle', true), + person('Nick Taylor', true), + person('Amy Guest', false), + person('RobbieTheWagner', true) + ], + hosts + ); + expect(sorted.map((p) => p.name)).toEqual([ + 'RobbieTheWagner', + 'Adam Argyle', + 'Nick Taylor', + 'Amy Guest', + 'Zed Guest' + ]); + }); + + it('credits a regular host who appeared as a guest among the guests', () => { + const sorted = sortCast( + [person('Adam Argyle', false), person('Chuck Carpenter', true), person('RobbieTheWagner', true)], + hosts + ); + expect(sorted.map((p) => `${p.name}${p.isHost ? '' : ' (guest)'}`)).toEqual([ + 'RobbieTheWagner', + 'Chuck Carpenter', + 'Adam Argyle (guest)' + ]); + }); +}); + +describe('voiceFor', () => { + const cues = [ + { s: 0, t: 'Hi', v: 0, n: 'Robbie Wagner' }, + { s: 5, t: 'Hey', v: 1, n: 'Adam Argyle' }, + { s: 9, t: 'Hello', v: 2, n: 'Denver Cramer' } + ]; + + it('matches people to the voice they speak in, loosely by first name', () => { + expect(voiceFor('RobbieTheWagner', cues)).toBe(0); + expect(voiceFor('Adam Argyle', cues)).toBe(1); + }); + + it('matches a shared surname when first names differ', () => { + const chuck = [ + { s: 0, t: 'Hi', v: 0, n: 'Chuck Carpenter' }, + { s: 5, t: 'Hey', v: 1, n: 'Adam Argyle' } + ]; + expect(voiceFor('Charles William Carpenter III', chuck)).toBe(0); + expect(voiceFor('Robbie Wagner', chuck)).toBeUndefined(); + }); + + it('gives no voice to guests outside the two main voices, or without a transcript', () => { + expect(voiceFor('Denver Cramer', cues)).toBeUndefined(); + expect(voiceFor('Robbie Wagner', null)).toBeUndefined(); + }); +}); diff --git a/tests/unit/cues.test.ts b/tests/unit/cues.test.ts new file mode 100644 index 0000000..2f7050f --- /dev/null +++ b/tests/unit/cues.test.ts @@ -0,0 +1,55 @@ +import { describe, expect, it } from 'vitest'; +import { + mergeIntoLines, + parseMarkdownCues +} from 'starpod/src/lib/cues'; + +describe('parseMarkdownCues', () => { + const markdown = [ + '[00:00:00] **Intro:** Welcome to the show. Pour a glass.', + '[00:00:10] **Robbie Wagner:** Hey everybody. Good to be here.', + '[00:00:20] **Adam Argyle:** Hi. I brought *the* whiskey.', + '[00:00:30] **Robbie Wagner:** Great.', + '[00:00:40] **Adam Argyle:** Cheers.' + ].join('\n\n'); + const cues = parseMarkdownCues(markdown); + + it('reads bold speaker names and strips inline markdown', () => { + expect(cues[0].n).toBe('Intro'); + expect(cues.find((cue) => cue.t.includes('brought'))?.t).toBe( + 'Hi. I brought the whiskey.' + ); + }); + + it('gives the two people who talk most the two signature voices', () => { + const voiceOf = (name: string) => cues.find((cue) => cue.n === name)?.v; + expect(voiceOf('Robbie Wagner')).toBe(0); + expect(voiceOf('Adam Argyle')).toBe(1); + expect(voiceOf('Intro')).toBe(2); + }); + + it('spreads sentences across their paragraph instead of stacking them', () => { + const starts = cues.map((cue) => cue.s); + expect(new Set(starts).size).toBe(starts.length); + expect(starts).toEqual([...starts].sort((a, b) => a - b)); + }); +}); + +describe('mergeIntoLines', () => { + it('leaves voice unset for captions without speakers', () => { + const lines = mergeIntoLines([ + { start: 0, text: 'Hello there.' }, + { start: 2, text: 'General Kenobi.' } + ]); + expect(lines.every((line) => line.v === undefined)).toBe(true); + }); + + it('starts a new line when the speaker changes', () => { + const lines = mergeIntoLines([ + { start: 0, text: 'One', speaker: 'A' }, + { start: 1, text: 'two', speaker: 'A' }, + { start: 2, text: 'Three', speaker: 'B' } + ]); + expect(lines.map((line) => line.t)).toEqual(['One two', 'Three']); + }); +}); diff --git a/tests/unit/feed-media.test.ts b/tests/unit/feed-media.test.ts new file mode 100644 index 0000000..fd4567a --- /dev/null +++ b/tests/unit/feed-media.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it } from 'vitest'; +import { extractVideosByGuid, isVideoType } from 'starpod/src/lib/feed-media'; + +const feed = ` + +With videoflightcast:AAA + + + +Audio onlyflightcast:BBB + + +Audio alternate firstCCC + + + +`; + +describe('extractVideosByGuid', () => { + const videos = extractVideosByGuid(feed); + + it('finds an HLS alternate enclosure and decodes its URL', () => { + expect(videos.get('flightcast:AAA')).toEqual({ + src: 'https://example.com/v/a.m3u8?x=1&y=2', + type: 'application/x-mpegURL' + }); + }); + + it('leaves audio-only items out', () => { + expect(videos.has('flightcast:BBB')).toBe(false); + }); + + it('skips non-video alternates and takes the first video one', () => { + expect(videos.get('CCC')).toEqual({ + src: 'https://example.com/c.mp4', + type: 'video/mp4' + }); + }); +}); + +describe('isVideoType', () => { + it('accepts video and HLS types only', () => { + expect(isVideoType('video/mp4')).toBe(true); + expect(isVideoType('application/vnd.apple.mpegurl')).toBe(true); + expect(isVideoType('audio/mpeg')).toBe(false); + }); +}); From d0670ebd28e178c7b10780a70339c3fd63589731 Mon Sep 17 00:00:00 2001 From: Robert Wagner Date: Mon, 16 Nov 2026 10:03:25 -0500 Subject: [PATCH 2/3] Run CI and CodeRabbit on stacked PRs; pin e2e to Ubuntu 24.04 ubuntu-latest moved to 26.04, where Playwright 1.60 cannot install its browsers, so the e2e job failed before running any test. Also run the CI workflow for PRs whose base is another PR's branch, and let CodeRabbit auto-review them. Co-Authored-By: Claude Opus 5.5 --- .coderabbit.yaml | 7 +++++++ .github/workflows/ci.yml | 5 +++-- 2 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 .coderabbit.yaml diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 0000000..3fa0b8a --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,7 @@ +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json +reviews: + auto_review: + enabled: true + # Review stacked PRs too, not only PRs that target the default branch. + base_branches: + - '.*' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 002838c..c4b7dc0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,8 @@ name: Lint & Tests on: push: branches: [main] + # Every PR, including ones stacked on another PR's branch. pull_request: - branches: [main] jobs: lint: timeout-minutes: 10 @@ -57,7 +57,8 @@ jobs: e2e: timeout-minutes: 60 - runs-on: ubuntu-latest + # Playwright 1.60 can't install browsers on ubuntu-latest (26.04) yet. + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 From ac95033c9a9eaa6591b904e369547290bd312004 Mon Sep 17 00:00:00 2001 From: Robert Wagner Date: Mon, 16 Nov 2026 10:42:17 -0500 Subject: [PATCH 3/3] Address CodeRabbit review on the video and transcript data layer - feed-media: decode XML references in one pass (numeric references too), accept single-quoted attributes, read CDATA guids, and put a 10s deadline on the feed request so a stalled response can't hold up the build. - cues: accept the Podcast Namespace JSON fields (startTime/body) as well as start/text, read CRLF markdown transcripts, and bound the transcript fetch. - cast: an exact name match wins over a loose first-name match. - Register /api/cues/[episode].json in the integration's routes. Co-Authored-By: Claude Opus 5.5 --- packages/starpod/src/index.ts | 1 + packages/starpod/src/lib/cast.ts | 17 +++++--- packages/starpod/src/lib/cues.ts | 39 +++++++++++------ packages/starpod/src/lib/feed-media.ts | 60 +++++++++++++++++++++----- tests/unit/cast.test.ts | 9 ++++ tests/unit/cues.test.ts | 25 +++++++++++ tests/unit/feed-media.test.ts | 10 +++++ 7 files changed, 131 insertions(+), 30 deletions(-) diff --git a/packages/starpod/src/index.ts b/packages/starpod/src/index.ts index 047bad1..c555d9d 100644 --- a/packages/starpod/src/index.ts +++ b/packages/starpod/src/index.ts @@ -145,6 +145,7 @@ const ROUTES: Array<{ pattern: string; entrypoint: string }> = [ { pattern: '/robots.txt', entrypoint: 'robots.txt.ts' }, { pattern: '/api/contact', entrypoint: 'api/contact.ts' }, { pattern: '/api/episodes/[page].json', entrypoint: 'api/episodes/[page].json.ts' }, + { pattern: '/api/cues/[episode].json', entrypoint: 'api/cues/[episode].json.ts' }, { pattern: '/api/episodes/search.json', entrypoint: 'api/episodes/search.json.ts' diff --git a/packages/starpod/src/lib/cast.ts b/packages/starpod/src/lib/cast.ts index 4098189..0719a4a 100644 --- a/packages/starpod/src/lib/cast.ts +++ b/packages/starpod/src/lib/cast.ts @@ -75,11 +75,14 @@ export function voiceFor( if (!cues?.length) { return undefined; } - for (const voice of [0, 1]) { - const speaker = cues.find((cue) => cue.v === voice && cue.n)?.n; - if (speaker && sameName(name, speaker)) { - return voice; - } - } - return undefined; + const speakers = [0, 1].map((voice) => ({ + voice, + speaker: cues.find((cue) => cue.v === voice && cue.n)?.n + })); + // An exact name wins over a loose one, whichever voice comes first. + const exact = tokens(name).join(' '); + const match = + speakers.find(({ speaker }) => speaker && tokens(speaker).join(' ') === exact) ?? + speakers.find(({ speaker }) => speaker && sameName(name, speaker)); + return match?.voice; } diff --git a/packages/starpod/src/lib/cues.ts b/packages/starpod/src/lib/cues.ts index 35837ed..853efdd 100644 --- a/packages/starpod/src/lib/cues.ts +++ b/packages/starpod/src/lib/cues.ts @@ -106,7 +106,7 @@ function stripInlineMarkdown(text: string): string { */ export function parseMarkdownCues(markdown: string): Array { const paragraphs: Array<{ start: number; speaker?: string; sentences: Array }> = []; - for (const block of markdown.split(/\n{2,}/)) { + for (const block of markdown.replace(/\r\n?/g, '\n').split(/\n{2,}/)) { const match = block.replace(/\n/g, ' ').match(MARKDOWN_LINE); if (!match) { continue; @@ -144,6 +144,28 @@ export function parseMarkdownCues(markdown: string): Array { return mergeIntoLines(segments); } +type JsonSegment = { + body?: string; + speaker?: string; + start?: number; + startTime?: number; + text?: string; +}; + +/** + * Segments from a JSON transcript. The Podcast Namespace format names its + * fields `startTime` and `body`; `start` and `text` are accepted as well. + */ +export function jsonSegments(data: { segments?: Array }): Array { + return (data.segments ?? []).flatMap((segment) => { + const start = segment.startTime ?? segment.start; + const text = (segment.body ?? segment.text)?.trim(); + return typeof start === 'number' && text + ? [{ start, text, speaker: segment.speaker || undefined }] + : []; + }); +} + /** * Timed lines from the feed's `` (VTT/SRT cues or JSON * segments). Returns `null` when none is available. @@ -170,7 +192,9 @@ async function fetchRssCues( url: string ): Promise | null> { try { - const response = await fetch(url); + // A deadline on the whole request, body included, so a stalled + // transcript can't hold up the build. + const response = await fetch(url, { signal: AbortSignal.timeout(10_000) }); if (!response.ok) { return null; } @@ -182,16 +206,7 @@ async function fetchRssCues( ).toLowerCase(); if (type.includes('json')) { - const data = JSON.parse(raw) as { - segments?: Array<{ text?: string; start?: number; speaker?: string }>; - }; - const segments = (data.segments ?? []) - .filter((s) => s.text?.trim() && typeof s.start === 'number') - .map((s) => ({ - start: s.start!, - text: s.text!.trim(), - speaker: s.speaker || undefined - })); + const segments = jsonSegments(JSON.parse(raw)); return segments.length ? mergeIntoLines(segments) : null; } diff --git a/packages/starpod/src/lib/feed-media.ts b/packages/starpod/src/lib/feed-media.ts index 45ef606..87a6978 100644 --- a/packages/starpod/src/lib/feed-media.ts +++ b/packages/starpod/src/lib/feed-media.ts @@ -13,19 +13,53 @@ export interface FeedVideo { } const HLS_TYPES = ['application/x-mpegurl', 'application/vnd.apple.mpegurl']; +const FETCH_TIMEOUT_MS = 10_000; +const NAMED_ENTITIES: Record = { + amp: '&', + apos: "'", + gt: '>', + lt: '<', + quot: '"' +}; + +/** + * Decode XML character references in one pass, so each reference in the + * original text is decoded exactly once (`&lt;` stays the literal `<`). + */ function decodeEntities(value: string): string { - return value - .replace(/&/g, '&') - .replace(/</g, '<') - .replace(/>/g, '>') - .replace(/"/g, '"') - .replace(/'/g, "'"); + return value.replace( + /&(?:#(\d+)|#x([\da-f]+)|(amp|apos|gt|lt|quot));/gi, + (reference, decimal?: string, hex?: string, name?: string) => { + if (name) { + return NAMED_ENTITIES[name.toLowerCase()]; + } + const codePoint = decimal ? Number(decimal) : parseInt(hex!, 16); + return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : reference; + } + ); +} + +// Attribute names are fixed by this module, never taken from the feed. +const ATTRIBUTE_PATTERNS: Record<'type' | 'uri', RegExp> = { + type: /\btype\s*=\s*(["'])(.*?)\1/i, + uri: /\buri\s*=\s*(["'])(.*?)\1/i +}; + +function attribute(tag: string, name: 'type' | 'uri'): string | undefined { + const match = tag.match(ATTRIBUTE_PATTERNS[name]); + return match ? decodeEntities(match[2]) : undefined; } -function attribute(tag: string, name: string): string | undefined { - const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`, 'i')); - return match ? decodeEntities(match[1]) : undefined; +/** An element's character data: CDATA sections as-is, the rest decoded. */ +function characterData(raw: string): string { + return raw + .split(/()/) + .map((part) => + part.startsWith(' { const sourceTag = enclosure.match(/]*>/i)?.[0]; const src = sourceTag && attribute(sourceTag, 'uri'); if (src) { - videos.set(decodeEntities(guid.trim()), { src, type }); + videos.set(characterData(guid), { src, type }); break; } } @@ -75,7 +109,11 @@ export async function fetchFeedVideos( feedUrl: string ): Promise> { try { - const response = await fetch(feedUrl); + // A deadline on the whole request, body included: a stalled response + // must not hold up the build, which then falls back to audio. + const response = await fetch(feedUrl, { + signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) + }); if (!response.ok) { return new Map(); } diff --git a/tests/unit/cast.test.ts b/tests/unit/cast.test.ts index e516cb7..5600758 100644 --- a/tests/unit/cast.test.ts +++ b/tests/unit/cast.test.ts @@ -60,6 +60,15 @@ describe('voiceFor', () => { expect(voiceFor('Robbie Wagner', chuck)).toBeUndefined(); }); + it('prefers an exact name over a loose first-name match', () => { + const adams = [ + { s: 0, t: 'Hi', v: 0, n: 'Adam Smith' }, + { s: 5, t: 'Hey', v: 1, n: 'Adam Argyle' } + ]; + expect(voiceFor('Adam Argyle', adams)).toBe(1); + expect(voiceFor('Adam Smith', adams)).toBe(0); + }); + it('gives no voice to guests outside the two main voices, or without a transcript', () => { expect(voiceFor('Denver Cramer', cues)).toBeUndefined(); expect(voiceFor('Robbie Wagner', null)).toBeUndefined(); diff --git a/tests/unit/cues.test.ts b/tests/unit/cues.test.ts index 2f7050f..073312f 100644 --- a/tests/unit/cues.test.ts +++ b/tests/unit/cues.test.ts @@ -1,5 +1,6 @@ import { describe, expect, it } from 'vitest'; import { + jsonSegments, mergeIntoLines, parseMarkdownCues } from 'starpod/src/lib/cues'; @@ -14,6 +15,10 @@ describe('parseMarkdownCues', () => { ].join('\n\n'); const cues = parseMarkdownCues(markdown); + it('reads Windows (CRLF) line endings the same way', () => { + expect(parseMarkdownCues(markdown.replace(/\n/g, '\r\n'))).toEqual(cues); + }); + it('reads bold speaker names and strips inline markdown', () => { expect(cues[0].n).toBe('Intro'); expect(cues.find((cue) => cue.t.includes('brought'))?.t).toBe( @@ -53,3 +58,23 @@ describe('mergeIntoLines', () => { expect(lines.map((line) => line.t)).toEqual(['One two', 'Three']); }); }); + +describe('jsonSegments', () => { + it('reads the Podcast Namespace startTime/body fields', () => { + expect( + jsonSegments({ segments: [{ startTime: 0.5, body: ' Hello ', speaker: 'Alice' }] }) + ).toEqual([{ start: 0.5, text: 'Hello', speaker: 'Alice' }]); + }); + + it('also reads start/text, and drops segments without a time or text', () => { + expect( + jsonSegments({ + segments: [ + { start: 2, text: 'Hi' }, + { start: 3, text: ' ' }, + { text: 'No time' } + ] + }) + ).toEqual([{ start: 2, text: 'Hi', speaker: undefined }]); + }); +}); diff --git a/tests/unit/feed-media.test.ts b/tests/unit/feed-media.test.ts index fd4567a..4b42768 100644 --- a/tests/unit/feed-media.test.ts +++ b/tests/unit/feed-media.test.ts @@ -10,6 +10,9 @@ const feed = ` Audio onlyflightcast:BBB +Quoting + + Audio alternate firstCCC @@ -26,6 +29,13 @@ describe('extractVideosByGuid', () => { }); }); + it('reads CDATA guids, single-quoted attributes, and each reference once', () => { + expect(videos.get('episode-A')).toEqual({ + src: 'https://example.com/q.mp4?a=1&b=<2', + type: 'video/mp4' + }); + }); + it('leaves audio-only items out', () => { expect(videos.has('flightcast:BBB')).toBe(false); });