aboutsummaryrefslogtreecommitdiff
path: root/castle-search/src/http.ts
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-18 12:44:11 +0000
committerIgor Soarez <igor@soarez.org>2026-11-18 12:44:11 +0000
commit720b4b7f41a6394c074c22336bb22cc6e006b554 (patch)
tree5b3d36d06ad55fd6d4cdb4f24a8c0d9c7328fcec /castle-search/src/http.ts
parent358cf43172f0028b079c49fa16f376e400d6cc25 (diff)
castle-search: YouTube transcripts, filed in a folder and returnedHEADmaster
POST /youtube-transcript, described at /youtube/openapi.json: captions only, manual over automatic, rolling repeats removed, filed as <upload date>-<Title>.txt. yt-dlp updates itself daily and on failure; a 429 falls back to youtube-transcript-api. Hermes's recipe from bambos.
Diffstat (limited to 'castle-search/src/http.ts')
-rw-r--r--castle-search/src/http.ts70
1 files changed, 67 insertions, 3 deletions
diff --git a/castle-search/src/http.ts b/castle-search/src/http.ts
index 8efc4c5..076c624 100644
--- a/castle-search/src/http.ts
+++ b/castle-search/src/http.ts
@@ -22,8 +22,10 @@
*
* POST /x-search, /x-post, /x-user and /x-trends read X instead (x-search.ts),
* through the browser's signed-in X session, and GET /openapi.json describes
- * them, so that Open WebUI can offer them as tools ("X.com"). Each answers 502
- * with `{ "error" }` on failure.
+ * them, so that Open WebUI can offer them as tools ("X.com"). POST
+ * /youtube-transcript files a YouTube video's transcript and returns it
+ * (youtube.ts), described at GET /youtube/openapi.json ("YouTube"). Each
+ * answers 502 with `{ "error" }` on failure.
*/
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
@@ -47,6 +49,7 @@ import {
type XUserOutcome,
type XUserRequest,
} from "./x-search.ts";
+import { DEFAULT_MAX_CHARS, type TranscriptOutcome, type TranscriptRequest, videoIdOf, youtubeTranscript } from "./youtube.ts";
export const DEFAULT_LISTEN = "127.0.0.1:11158";
const MAX_BODY_BYTES = 64 * 1024;
@@ -171,6 +174,25 @@ export const handleXTrends = async (raw: string, run: XTrendsReader, signal: Abo
return answer(() => run(tab as XTrendTab, signal));
};
+export type TranscriptFetcher = (request: TranscriptRequest, signal: AbortSignal) => Promise<TranscriptOutcome>;
+
+/** POST /youtube-transcript: `{ url, language?, max_chars? }` in, the transcript and where it was filed out. */
+export const handleTranscript = async (raw: string, run: TranscriptFetcher, signal: AbortSignal): Promise<Reply> => {
+ const body = jsonBody(raw);
+ if (isReply(body)) return body;
+ if (typeof body["url"] !== "string" || !videoIdOf(body["url"])) {
+ return { status: 400, body: { error: "url must be a YouTube video link (youtube.com/watch?v=..., youtu.be/..., shorts/...)" } };
+ }
+ const language = body["language"];
+ if (language !== undefined && (typeof language !== "string" || !/^[A-Za-z]{2,3}(-[A-Za-z0-9]+)?$/.test(language))) {
+ return { status: 400, body: { error: "language must be a language code such as en, pt or en-GB" } };
+ }
+ const max = body["max_chars"];
+ const maxChars = typeof max === "number" && Number.isFinite(max) ? Math.max(1000, Math.trunc(max)) : DEFAULT_MAX_CHARS;
+ const url = body["url"];
+ return answer(() => run({ url, language: language as string | undefined, maxChars }, signal));
+};
+
const jsonSchema = (properties: Record<string, unknown>, required: string[]) => ({
required: true,
content: { "application/json": { schema: { type: "object", required, properties } } },
@@ -267,6 +289,43 @@ export const OPENAPI = {
},
} as const;
+/** The YouTube tool's own description, so Open WebUI lists it apart from X.com. */
+export const YOUTUBE_OPENAPI = {
+ openapi: "3.1.0",
+ info: {
+ title: "YouTube",
+ version: "1.0.0",
+ description: "A YouTube video's transcript, filed in Igor's Nextcloud transcript folder and returned.",
+ },
+ paths: {
+ "/youtube-transcript": {
+ post: {
+ operationId: "youtube_transcript",
+ summary: "Get a YouTube video's transcript",
+ description:
+ "Fetch a YouTube video's transcript from its link: the video's captions (human-written when it " +
+ "has them, YouTube's automatic ones otherwise) as clean prose, with its title, channel, upload " +
+ "date and length. It is also filed in Igor's Nextcloud, in the transcript folder, as " +
+ "<upload date>-<Title>.txt; a video filed before is read from there. Use it whenever a YouTube " +
+ "link comes up and its content matters: to summarise it, answer questions about it, or quote " +
+ "it. Automatic captions garble names and numbers: say so when one matters.",
+ requestBody: jsonSchema(
+ {
+ url: { type: "string", description: "The video's link: youtube.com/watch?v=..., youtu.be/..., shorts/..." },
+ language: { type: "string", default: "en", description: "Caption language code, such as en or pt" },
+ max_chars: { type: "integer", minimum: 1000, default: DEFAULT_MAX_CHARS, description: "Most characters of text to return; the file always has all of it" },
+ },
+ ["url"],
+ ),
+ responses: {
+ "200": { description: "The transcript and where it was filed", content: { "application/json": { schema: { type: "object" } } } },
+ "502": { description: "No transcript; error says why", content: { "application/json": { schema: { type: "object" } } } },
+ },
+ },
+ },
+ },
+} as const;
+
const readBody = (req: IncomingMessage): Promise<string> =>
new Promise((resolve, reject) => {
let size = 0;
@@ -313,15 +372,20 @@ const main = (): void => {
send(res, { status: 200, body: OPENAPI });
return;
}
+ if (req.method === "GET" && path === "/youtube/openapi.json") {
+ send(res, { status: 200, body: YOUTUBE_OPENAPI });
+ return;
+ }
const xRoutes: Record<string, (raw: string, signal: AbortSignal) => Promise<Reply>> = {
"/x-search": (raw, signal) => handleXSearch(raw, xSearch, signal),
"/x-post": (raw, signal) => handleXPost(raw, xPost, signal),
"/x-user": (raw, signal) => handleXUser(raw, xUser, signal),
"/x-trends": (raw, signal) => handleXTrends(raw, xTrends, signal),
+ "/youtube-transcript": (raw, signal) => handleTranscript(raw, youtubeTranscript, signal),
};
const xRoute = xRoutes[path ?? ""];
if (req.method !== "POST" || (path !== "/" && path !== "/search" && !xRoute)) {
- send(res, { status: 404, body: { error: "POST a search to / or /search, or an X read to /x-search, /x-post, /x-user or /x-trends" } });
+ send(res, { status: 404, body: { error: "POST a search to / or /search, an X read to /x-search, /x-post, /x-user or /x-trends, or a YouTube link to /youtube-transcript" } });
return;
}
// Stop the search, and free its tab, if the client goes away first.