1export interface YouTubeTranscriptSegment {
2  start: number;
3  end: number;
4  text: string;
5}
6 
7export interface YouTubeChapter {
8  title: string;
9  time: number;
10}
11 
12interface RenderYouTubeTranscriptMarkdownInput {
13  description?: string;
14  segments: YouTubeTranscriptSegment[];
15  chapters: YouTubeChapter[];
16}
17 
18const DESCRIPTION_CHAPTER_RE = /^((?:\d{1,2}:)?\d{1,2}:\d{2})(?:\s+[-|:]\s+|\s+)(.+)$/;
19const YOUTUBE_THUMBNAIL_VARIANTS = [
20  "maxresdefault.jpg",
21  "sddefault.jpg",
22  "hqdefault.jpg",
23  "mqdefault.jpg",
24  "default.jpg",
25];
26 
27export function isYouTubeHost(hostname: string): boolean {
28  return [
29    "youtube.com",
30    "www.youtube.com",
31    "m.youtube.com",
32    "youtu.be",
33  ].includes(hostname);
34}
35 
36export function parseYouTubeVideoId(url: URL): string | null {
37  if (url.hostname === "youtu.be") {
38    return url.pathname.split("/").filter(Boolean)[0] ?? null;
39  }
40 
41  if (url.pathname === "/watch") {
42    return url.searchParams.get("v");
43  }
44 
45  const shortsMatch = url.pathname.match(/^\/shorts\/([^/?#]+)/);
46  if (shortsMatch) {
47    return shortsMatch[1];
48  }
49 
50  const liveMatch = url.pathname.match(/^\/live\/([^/?#]+)/);
51  if (liveMatch) {
52    return liveMatch[1];
53  }
54 
55  return null;
56}
57 
58function parseTimestampValue(raw: string): number | null {
59  const parts = raw
60    .split(":")
61    .map((part) => Number.parseInt(part, 10))
62    .filter((part) => Number.isFinite(part));
63 
64  if (parts.length < 2 || parts.length > 3) {
65    return null;
66  }
67 
68  if (parts.some((part) => part < 0)) {
69    return null;
70  }
71 
72  if (parts.length === 2) {
73    const [minutes, seconds] = parts;
74    return minutes * 60 + seconds;
75  }
76 
77  const [hours, minutes, seconds] = parts;
78  return hours * 3600 + minutes * 60 + seconds;
79}
80 
81export function formatTimestamp(totalSeconds: number): string {
82  const rounded = Math.max(0, Math.floor(totalSeconds));
83  const hours = Math.floor(rounded / 3600);
84  const minutes = Math.floor((rounded % 3600) / 60);
85  const seconds = rounded % 60;
86 
87  if (hours > 0) {
88    return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
89  }
90  return `${minutes}:${String(seconds).padStart(2, "0")}`;
91}
92 
93export function formatTimestampRange(start: number, end: number): string {
94  const safeStart = Math.max(0, start);
95  const safeEnd = Math.max(safeStart, end);
96  return `[${formatTimestamp(safeStart)} -> ${formatTimestamp(safeEnd)}]`;
97}
98 
99export function normalizeYouTubeChapters(chapters: YouTubeChapter[]): YouTubeChapter[] {
100  const seenTimes = new Set<number>();
101 
102  return chapters
103    .map((chapter) => ({
104      title: chapter.title.trim(),
105      time: Math.max(0, Math.floor(chapter.time)),
106    }))
107    .filter((chapter) => chapter.title)
108    .sort((left, right) => left.time - right.time)
109    .filter((chapter) => {
110      if (seenTimes.has(chapter.time)) {
111        return false;
112      }
113      seenTimes.add(chapter.time);
114      return true;
115    });
116}
117 
118export function parseYouTubeDescriptionChapters(description?: string | null): YouTubeChapter[] {
119  if (!description) {
120    return [];
121  }
122 
123  const chapters: YouTubeChapter[] = [];
124  const seen = new Set<string>();
125 
126  for (const rawLine of description.replace(/\r\n/g, "\n").split("\n")) {
127    const line = rawLine.trim();
128    if (!line) {
129      continue;
130    }
131 
132    const match = line.match(DESCRIPTION_CHAPTER_RE);
133    if (!match) {
134      continue;
135    }
136 
137    const time = parseTimestampValue(match[1]);
138    const title = match[2]?.trim();
139    if (time === null || !title) {
140      continue;
141    }
142 
143    const key = `${time}:${title.toLowerCase()}`;
144    if (seen.has(key)) {
145      continue;
146    }
147 
148    seen.add(key);
149    chapters.push({ title, time });
150  }
151 
152  const normalized = normalizeYouTubeChapters(chapters);
153  if (normalized.length >= 2) {
154    return normalized;
155  }
156 
157  if (normalized.length === 1 && normalized[0]?.time === 0) {
158    return normalized;
159  }
160 
161  return [];
162}
163 
164function renderDescriptionMarkdown(description: string): string {
165  return description
166    .replace(/\r\n/g, "\n")
167    .trim()
168    .split(/\n{2,}/)
169    .map((block) => block.split("\n").map((line) => line.trimEnd()).join("  \n"))
170    .join("\n\n")
171    .trim();
172}
173 
174function renderSegmentLine(segment: YouTubeTranscriptSegment): string {
175  return `${formatTimestampRange(segment.start, segment.end)} ${segment.text}`;
176}
177 
178export function renderYouTubeTranscriptMarkdown({
179  description,
180  segments,
181  chapters,
182}: RenderYouTubeTranscriptMarkdownInput): string {
183  if (segments.length === 0) {
184    return "";
185  }
186 
187  const parts: string[] = [];
188  const normalizedDescription = description?.trim();
189  const transcriptEnd = segments.reduce((maxEnd, segment) => Math.max(maxEnd, segment.end, segment.start), 0);
190  const normalizedChapters = normalizeYouTubeChapters(chapters).filter(
191    (chapter) => transcriptEnd <= 0 || chapter.time < transcriptEnd,
192  );
193 
194  if (normalizedDescription) {
195    parts.push("## Description");
196    parts.push(renderDescriptionMarkdown(normalizedDescription));
197  }
198 
199  if (normalizedChapters.length > 0) {
200    parts.push("## Chapters");
201 
202    for (let index = 0; index < normalizedChapters.length; index += 1) {
203      const chapter = normalizedChapters[index];
204      const nextChapter = normalizedChapters[index + 1];
205      const chapterEnd = nextChapter ? nextChapter.time : transcriptEnd;
206      const chapterSegments = segments.filter(
207        (segment) => segment.start >= chapter.time && segment.start < chapterEnd,
208      );
209 
210      parts.push(`### ${chapter.title} ${formatTimestampRange(chapter.time, chapterEnd)}`);
211 
212      if (chapterSegments.length > 0) {
213        parts.push(chapterSegments.map(renderSegmentLine).join("\n"));
214      }
215    }
216  } else {
217    parts.push("## Transcript");
218    parts.push(segments.map(renderSegmentLine).join("\n"));
219  }
220 
221  return parts.filter(Boolean).join("\n\n").trim();
222}
223 
224function normalizeThumbnailKey(url: string): string {
225  try {
226    const parsed = new URL(url);
227    return `${parsed.origin}${parsed.pathname}`;
228  } catch {
229    return url;
230  }
231}
232 
233export function buildYouTubeThumbnailCandidates(videoId: string, listedUrls: string[]): string[] {
234  const candidates = [
235    ...YOUTUBE_THUMBNAIL_VARIANTS.map((variant) => `https://i.ytimg.com/vi/${videoId}/${variant}`),
236    ...listedUrls,
237  ];
238 
239  const seen = new Set<string>();
240  return candidates.filter((candidate) => {
241    if (!candidate) {
242      return false;
243    }
244 
245    const key = normalizeThumbnailKey(candidate);
246    if (seen.has(key)) {
247      return false;
248    }
249 
250    seen.add(key);
251    return true;
252  });
253}
254