@mekuru/youtube 0.0.0-stage → 0.1.2

package/README.jp.md

@@ -0,0 +1,19 @@
+# @mekuru/youtube
+
+[English](README.md)
+
+Mekuru Movie Maker の動画を YouTube にアップロードします。動画のパス、タイトル、説明文、タグ、公開設定、任意のサムネイルを YAML で指定します。Bun 1.4 以上が必要です。
+
+[投稿ガイド](../../docs/reference/Upload.jp.md) に従って `configs/youtube.yaml` と OAuth クライアントの設定を準備し、プロジェクトのフォルダから実行します。
+
+```sh
+bun add -d @mekuru/youtube
+bunx mekuru-youtube --dry-run
+bunx mekuru-youtube
+```
+
+- 既定の設定ファイルは `configs/youtube.yaml` です。引数に別の YAML のパスを渡せます。複数渡すと順にアップロードします。
+- 設定内のファイルパスはプロジェクトのフォルダからの相対パスです。
+- `--dry-run` はログインやアップロードをせずに設定を表示します。初回のアップロードでは Google にログインするためのブラウザが開きます。
+
+[設定例](../../example/configs/youtube.yaml)

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @mekuru/youtube
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[日本語](README.jp.md)
+
+Uploads Mekuru Movie Maker videos to YouTube using a YAML file for the video path, title, description, tags, visibility, and optional thumbnail. Requires Bun 1.4 or later.
+
+Prepare `configs/youtube.yaml` and the OAuth client configuration described in the [upload guide](../../docs/reference/Upload.md), then run from the project folder:
+
+```sh
+bun add -d @mekuru/youtube
+bunx mekuru-youtube --dry-run
+bunx mekuru-youtube
+```
+
+- The default configuration file is `configs/youtube.yaml`; pass other YAML paths as arguments to upload multiple videos in order.
+- File paths in the configuration are relative to the project folder.
+- `--dry-run` displays the upload settings without signing in or uploading. The first upload opens a browser for Google sign-in.
+
+See the [example configuration](../../example/configs/youtube.yaml).

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@mekuru/youtube",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Uploads a video of Mekuru Movie Maker to YouTube with the title, description, ... written in youtube.yaml",
+  "type": "module",
+  "bin": {
+    "mekuru-youtube": "./src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,120 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SCOPE = "https://www.googleapis.com/auth/youtube.upload";
+const SIGN_IN_TIMEOUT = 5 * 60_000;
+
+interface Client {
+  client_id: string;
+  client_secret: string;
+  auth_uri: string;
+  token_uri: string;
+}
+
+export const configDir = (): string => {
+  if (process.env.MEKURU_CONFIG_DIR) return process.env.MEKURU_CONFIG_DIR;
+  if (process.platform === "win32") return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "mekuru");
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "mekuru");
+};
+
+const readClient = async (file: string): Promise<Client> => {
+  if (!(await Bun.file(file).exists())) {
+    throw new Error(`no OAuth client: save the JSON of the OAuth client (a desktop app) of your Google Cloud project as ${file}`);
+  }
+  const c = ((await Bun.file(file).json()) as { installed?: Partial<Client> }).installed;
+  if (!c?.client_id || !c.client_secret) throw new Error(`${file} is not the JSON of an OAuth client of a desktop app`);
+  return {
+    client_id: c.client_id,
+    client_secret: c.client_secret,
+    auth_uri: c.auth_uri ?? "https://accounts.google.com/o/oauth2/auth",
+    token_uri: c.token_uri ?? "https://oauth2.googleapis.com/token",
+  };
+};
+
+interface TokenResponse {
+  ok: boolean;
+  access_token?: string;
+  refresh_token?: string;
+  error?: string;
+  error_description?: string;
+}
+
+const requestToken = async (client: Client, params: Record<string, string>): Promise<TokenResponse> => {
+  const res = await fetch(client.token_uri, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: client.client_id, client_secret: client.client_secret, ...params }),
+  });
+  return { ok: res.ok, ...((await res.json().catch(() => ({}))) as Omit<TokenResponse, "ok">) };
+};
+
+const signIn = async (client: Client, open: (url: string) => void): Promise<{ access: string; refresh: string }> => {
+  const verifier = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64url");
+  const state = crypto.randomUUID();
+  let server: ReturnType<typeof Bun.serve> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let redirect = "";
+  try {
+    const code = await new Promise<string>((done, fail) => {
+      server = Bun.serve({
+        hostname: "127.0.0.1",
+        port: 0,
+        fetch(req) {
+          const got = new URL(req.url).searchParams;
+          if (got.get("state") !== state) return new Response(null, { status: 404 });
+          clearTimeout(timer);
+          const code = got.get("code");
+          if (code) done(code);
+          else fail(new Error(`the sign-in failed: ${got.get("error") ?? "no code"}`));
+          return new Response(
+            code
+              ? "<p>Mekuru Movie Maker: signed in to YouTube. You can close this tab.</p>"
+              : "<p>Mekuru Movie Maker: the sign-in failed. See the terminal.</p>",
+            { headers: { "content-type": "text/html; charset=utf-8", connection: "close" } },
+          );
+        },
+      });
+      redirect = `http://127.0.0.1:${server.port}`;
+      timer = setTimeout(() => fail(new Error("timed out waiting for the sign-in in the browser")), SIGN_IN_TIMEOUT);
+      const url = new URL(client.auth_uri);
+      url.search = new URLSearchParams({
+        client_id: client.client_id,
+        redirect_uri: redirect,
+        response_type: "code",
+        scope: SCOPE,
+        access_type: "offline",
+        prompt: "consent",
+        state,
+        code_challenge: new Bun.CryptoHasher("sha256").update(verifier).digest("base64url"),
+        code_challenge_method: "S256",
+      }).toString();
+      console.error(`Sign in to YouTube in the browser:\n  ${url}`);
+      open(url.toString());
+    });
+    const t = await requestToken(client, { code, code_verifier: verifier, grant_type: "authorization_code", redirect_uri: redirect });
+    if (!t.ok || !t.access_token || !t.refresh_token) throw new Error(`the sign-in failed: ${t.error_description ?? t.error ?? "no token"}`);
+    return { access: t.access_token, refresh: t.refresh_token };
+  } finally {
+    clearTimeout(timer);
+    await server?.stop();
+  }
+};
+
+export const accessToken = async (open: (url: string) => void): Promise<string> => {
+  const dir = configDir();
+  const client = await readClient(join(dir, "youtube-client.json"));
+  const tokenFile = join(dir, "youtube-token.json");
+  if (await Bun.file(tokenFile).exists()) {
+    const { refresh_token } = (await Bun.file(tokenFile).json()) as { refresh_token: string };
+    const t = await requestToken(client, { refresh_token, grant_type: "refresh_token" });
+    if (t.ok && t.access_token) return t.access_token;
+    if (t.error !== "invalid_grant") throw new Error(`cannot renew the sign-in: ${t.error_description ?? t.error ?? "no token"}`);
+    console.error("The sign-in to YouTube has expired.");
+  }
+  const { access, refresh } = await signIn(client, open);
+  await mkdir(dir, { recursive: true });
+  // Bun.write does not reliably apply mode when creating a file; keep the refresh token private.
+  await writeFile(tokenFile, `${JSON.stringify({ refresh_token: refresh })}\n`, { mode: 0o600 });
+  return access;
+};

package/src/cli.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { accessToken, configDir } from "./auth.ts";
+import { readSettings, videoResource, type VideoResource } from "./settings.ts";
+import { setThumbnail, uploadVideo } from "./upload.ts";
+
+const VERSION: string = (await Bun.file(new URL("../package.json", import.meta.url)).json()).version;
+const DEFAULT = "configs/youtube.yaml";
+
+const openBrowser = (url: string): void => {
+  const wsl = process.platform === "linux" && (!!process.env.WSL_INTEROP || existsSync("/proc/sys/fs/binfmt_misc/WSLInterop"));
+  const tries: string[][] = wsl
+    ? [["wslview"], ["cmd.exe", "/c", "start", ""]]
+    : process.platform === "darwin"
+      ? [["open"]]
+      : process.platform === "win32"
+        ? [["cmd", "/c", "start", ""]]
+        : [["xdg-open"]];
+  for (const [cmd, ...args] of tries) {
+    const target = cmd.startsWith("cmd") ? url.replaceAll("&", "^&") : url;
+    try {
+      Bun.spawn([cmd, ...args, target], { stdin: "ignore", stdout: "ignore", stderr: "ignore", cwd: wsl ? "/mnt/c" : undefined }).unref();
+      break;
+    } catch {}
+  }
+};
+
+const main = async (configs: string[], { dryRun = false }: { dryRun?: boolean }): Promise<void> => {
+  const uploads = await Promise.all(
+    (configs.length ? configs : [DEFAULT]).map(async (config) => {
+      const settings = await readSettings(config);
+      const file = resolve(settings.video ?? "video.mp4");
+      const thumbnail = settings.thumbnail === undefined ? undefined : resolve(settings.thumbnail);
+      for (const f of [file, thumbnail]) if (f && !(await Bun.file(f).exists())) throw new Error(`${f} does not exist (in ${config})`);
+      return { config, file, thumbnail, video: videoResource(settings) };
+    }),
+  );
+  if (dryRun) {
+    for (const { config, file, thumbnail, video } of uploads) console.log(JSON.stringify({ config, file, thumbnail, ...video }, null, 2));
+    console.log(`(the sign-in is kept in ${configDir()})`);
+    return;
+  }
+
+  const token = await accessToken(openBrowser);
+  for (const { config, file, thumbnail, video } of uploads) {
+    if (uploads.length > 1) console.log(`${config}:`);
+    await uploadOne(file, thumbnail, video, token);
+  }
+};
+
+const uploadOne = async (file: string, thumbnail: string | undefined, video: VideoResource, token: string): Promise<void> => {
+  const tty = process.stderr.isTTY;
+  const uploaded = await uploadVideo(file, video, token, {
+    progress: (sent, total) =>
+      tty && process.stderr.write(`\ruploading ${Math.floor((sent / total) * 100)}% (${(sent / 2 ** 20).toFixed(1)} / ${(total / 2 ** 20).toFixed(1)} MiB)`),
+  });
+  if (tty) process.stderr.write("\n");
+  console.log(`uploaded: https://youtu.be/${uploaded.id}`);
+  console.log(`edit:     https://studio.youtube.com/video/${uploaded.id}/edit`);
+  const privacy = uploaded.status?.privacyStatus;
+  if (privacy && privacy !== video.status.privacyStatus) {
+    console.error(
+      `note: the video is ${privacy}, not ${video.status.privacyStatus} (YouTube makes the uploads of an API project that has not passed its audit private: change it in YouTube Studio)`,
+    );
+  }
+  if (thumbnail) {
+    try {
+      await setThumbnail(uploaded.id, thumbnail, token);
+    } catch (e) {
+      console.error(`warning: ${(e as Error).message}`);
+      process.exitCode = 1;
+    }
+  }
+};
+
+new Command("mekuru-youtube")
+  .description(
+    "Uploads videos to YouTube, one for each YAML file with its settings: the video file, the title, description, tags, ... " +
+      "The paths are relative to the current folder (the project). The first time, it opens the browser to sign in to Google.",
+  )
+  .version(VERSION)
+  .argument("[config...]", `the YAML files of the settings (default: ${DEFAULT})`)
+  .option("--dry-run", "show what it would upload, without signing in or uploading")
+  .showHelpAfterError("(add --help for more information)")
+  .action(main)
+  .parseAsync()
+  .catch((e: Error) => {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  });

package/src/settings.ts

@@ -0,0 +1,75 @@
+export type Privacy = "private" | "unlisted" | "public";
+
+export interface Settings {
+  video?: string;
+  title: string;
+  description?: string | string[];
+  tags?: string[];
+  category?: string | number;
+  privacy?: Privacy;
+  publishAt?: string;
+  madeForKids?: boolean;
+  thumbnail?: string;
+}
+
+export interface VideoResource {
+  snippet: { title: string; description: string; tags?: string[]; categoryId: string };
+  status: { privacyStatus: Privacy; publishAt?: string; selfDeclaredMadeForKids?: boolean };
+}
+
+const KEYS = ["video", "title", "description", "tags", "category", "privacy", "publishAt", "madeForKids", "thumbnail"];
+const PRIVACY = ["private", "unlisted", "public"];
+
+const isStrings = (v: unknown): v is string[] => Array.isArray(v) && v.every((s) => typeof s === "string");
+const descriptionOf = (d: Settings["description"]): string => (Array.isArray(d) ? d.join("\n") : (d ?? "")).trimEnd();
+
+const checkSettings = (value: unknown, name = "youtube.yaml"): Settings => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${name} must have the settings (title: …, description: …)`);
+  const s = value as Record<string, unknown>;
+  const errors: string[] = [];
+  for (const key of Object.keys(s)) if (!KEYS.includes(key)) errors.push(`unknown setting "${key}" (${KEYS.join(", ")})`);
+  if (s.video !== undefined && typeof s.video !== "string") errors.push(`"video" must be the path of the video file`);
+  if (typeof s.title !== "string" || !s.title.trim()) errors.push(`"title" is required`);
+  else if ([...s.title].length > 100) errors.push(`"title" is longer than 100 characters`);
+  else if (/[<>]/.test(s.title)) errors.push(`"title" cannot have < or >`);
+  if (s.description !== undefined) {
+    if (typeof s.description !== "string" && !isStrings(s.description)) errors.push(`"description" must be a string or an array of lines`);
+    else {
+      const text = descriptionOf(s.description);
+      if (Buffer.byteLength(text) > 5000) errors.push(`"description" is longer than 5000 bytes`);
+      if (/[<>]/.test(text)) errors.push(`"description" cannot have < or >`);
+    }
+  }
+  if (s.tags !== undefined) {
+    if (!isStrings(s.tags)) errors.push(`"tags" must be an array of strings`);
+    else if (s.tags.reduce((n, t) => n + [...t].length + (t.includes(" ") ? 2 : 0), Math.max(0, s.tags.length - 1)) > 500)
+      errors.push(`"tags" are longer than 500 characters in all`);
+  }
+  if (s.category !== undefined && !/^\d+$/.test(String(s.category))) errors.push(`"category" must be a category ID (a number such as 27)`);
+  if (s.privacy !== undefined && !PRIVACY.includes(s.privacy as string)) errors.push(`"privacy" must be ${PRIVACY.join(", ")}`);
+  if (s.publishAt !== undefined) {
+    if (typeof s.publishAt !== "string" || Number.isNaN(Date.parse(s.publishAt)))
+      errors.push(`"publishAt" must be a date and time (ISO 8601, such as 2026-11-01T18:00:00+09:00)`);
+    else if ((s.privacy ?? "private") !== "private") errors.push(`"publishAt" needs "privacy": "private" (the video is private until then)`);
+  }
+  if (s.madeForKids !== undefined && typeof s.madeForKids !== "boolean") errors.push(`"madeForKids" must be true or false`);
+  if (s.thumbnail !== undefined && typeof s.thumbnail !== "string") errors.push(`"thumbnail" must be the path of an image`);
+  if (errors.length) throw new Error(`${name}:\n  ${errors.join("\n  ")}`);
+  return s as unknown as Settings;
+};
+
+export const readSettings = async (file: string): Promise<Settings> => {
+  if (!(await Bun.file(file).exists())) throw new Error(`no ${file} (the video, its title, description, ... to upload)`);
+  let value: unknown;
+  try {
+    value = Bun.YAML.parse(await Bun.file(file).text());
+  } catch (e) {
+    throw new Error(`cannot read ${file}: ${(e as Error).message}`);
+  }
+  return checkSettings(value, file);
+};
+
+export const videoResource = (s: Settings): VideoResource => ({
+  snippet: { title: s.title, description: descriptionOf(s.description), tags: s.tags, categoryId: String(s.category ?? 22) },
+  status: { privacyStatus: s.privacy ?? "private", publishAt: s.publishAt, selfDeclaredMadeForKids: s.madeForKids },
+});

package/src/upload.ts

@@ -0,0 +1,95 @@
+import type { Privacy, VideoResource } from "./settings.ts";
+
+const CHUNK = 8 * 1024 * 1024;
+const RETRIES = 5;
+
+const API = "https://www.googleapis.com";
+
+const failure = async (what: string, res: Response): Promise<Error> => {
+  const text = await res.text();
+  let message = text.trim().slice(0, 500);
+  try {
+    const { error } = JSON.parse(text) as { error?: { message?: string; errors?: { reason?: string }[] } };
+    if (error?.message) message = error.message;
+    if (error?.errors?.[0]?.reason) message += ` (${error.errors[0].reason})`;
+  } catch {}
+  return new Error(`${what} failed: HTTP ${res.status}: ${message}`);
+};
+
+export interface UploadOptions {
+  progress?: (sent: number, total: number) => void;
+}
+
+export interface Uploaded {
+  id: string;
+  status?: { privacyStatus?: Privacy };
+}
+
+export const uploadVideo = async (file: string, video: VideoResource, token: string, options: UploadOptions = {}): Promise<Uploaded> => {
+  const { progress } = options;
+  const data = Bun.file(file);
+  if (!(await data.exists())) throw new Error(`${file} does not exist`);
+  const total = data.size;
+  if (total === 0) throw new Error(`${file} is empty`);
+  const type = data.type;
+  const start = await fetch(`${API}/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json; charset=UTF-8",
+      "X-Upload-Content-Length": String(total),
+      "X-Upload-Content-Type": type,
+    },
+    body: JSON.stringify(video),
+  });
+  if (!start.ok) throw await failure("the upload", start);
+  const session = start.headers.get("location");
+  if (!session) throw new Error("the upload failed: YouTube gave no upload URL");
+
+  const put = (range: string, body?: Buffer): Promise<Response> =>
+    fetch(session, {
+      method: "PUT",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": type, "Content-Range": range },
+      body: body ?? Buffer.alloc(0),
+    });
+  let offset = 0;
+  let retries = 0;
+  let query = false;
+  for (;;) {
+    let res: Response | undefined;
+    try {
+      if (query) res = await put(`bytes */${total}`);
+      else {
+        const size = Math.min(CHUNK, total - offset);
+        const body = Buffer.from(await data.slice(offset, offset + size).arrayBuffer());
+        res = await put(`bytes ${offset}-${offset + size - 1}/${total}`, body);
+      }
+    } catch {}
+    if (res?.status === 200 || res?.status === 201) {
+      progress?.(total, total);
+      return (await res.json()) as Uploaded;
+    }
+    if (res?.status === 308) {
+      const last = res.headers.get("range")?.match(/-(\d+)$/)?.[1];
+      const arrived = last === undefined ? 0 : Number(last) + 1;
+      if (arrived > offset) retries = 0;
+      offset = arrived;
+      query = false;
+      progress?.(offset, total);
+      continue;
+    }
+    if (res && res.status < 500) throw await failure("the upload", res);
+    if (++retries > RETRIES) throw res ? await failure("the upload", res) : new Error("the upload failed: the connection to YouTube failed");
+    await new Promise((go) => setTimeout(go, 1000 * 2 ** (retries - 1)));
+    query = true;
+  }
+};
+
+export const setThumbnail = async (id: string, file: string, token: string): Promise<void> => {
+  const res = await fetch(`${API}/upload/youtube/v3/thumbnails/set?videoId=${encodeURIComponent(id)}&uploadType=media`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": Bun.file(file).type },
+    body: Bun.file(file),
+  });
+  if (!res.ok) throw await failure("the thumbnail", res);
+};