@tacone/prosey 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tacone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# Prosey
+
+**Prosey** downloads YouTube transcripts to be printed or saved to a file.
+
+You can read, skim, search, copy, and manipulate the text using the tools you love the most.
+
+```bash
+npx prosey https://www.youtube.com/watch?v=dQw4w9WgXcQ
+```
+
+## Install
+
+### Quick — no install (npx)
+
+```bash
+npx prosey dQw4w9WgXcQ
+```
+
+### Global install (npm)
+
+```bash
+npm install -g prosey
+prosey dQw4w9WgXcQ
+```
+
+### From source (development)
+
+Uses **[Bun](https://bun.sh)** for development — scripts, package management,
+and running the TypeScript source directly.
+
+```bash
+git clone https://github.com/tacone/prosey.git
+cd prosey
+bun install
+bun run start -- dQw4w9WgXcQ
+```
+
+### Prebuilt binary
+
+Grab a compiled binary from the `dist/` directory (requires no runtime).
+
+## Usage
+
+```
+prosey [options] <video-url-or-id>
+prosey info [options] <video-url-or-id>
+```
+
+Pass a full YouTube URL or a bare video ID. The transcript is printed to
+stdout by default, with video details prepended.
+
+### Examples
+
+```bash
+# Basic — plain text with details
+prosey dQw4w9WgXcQ
+
+# Specify language
+prosey https://www.youtube.com/watch?v=dQw4w9WgXcQ --lang es
+
+# Include timestamps
+prosey dQw4w9WgXcQ -t
+
+# Save to file
+prosey dQw4w9WgXcQ -o transcript.txt
+
+# JSON output (timestamps always included)
+prosey dQw4w9WgXcQ --json
+
+# Transcript only, no video details
+prosey dQw4w9WgXcQ --no-details
+
+# List available transcript languages
+prosey dQw4w9WgXcQ --list
+
+# Show video metadata
+prosey info dQw4w9WgXcQ
+```
+
+## Options
+
+| Flag                    | Description                                                                                                    |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `--lang <code>`         | Language code (e.g. `en`, `fr`). Auto-detected if omitted.                                                     |
+| `-t`, `--timestamps`    | Prepend `[MM:SS]` to each line in text output.                                                                 |
+| `--list`                | List available transcript languages for the video, then exit.                                                  |
+| `-o`, `--output <path>` | Write output to file instead of stdout.                                                                        |
+| `--json`                | Output transcript as a JSON array. Each item includes `text`, `offset` (seconds), `duration`, and `timestamp`. |
+| `--text`                | Output as plain text (default).                                                                                |
+| `--details`             | Prepend video details (title, channel, duration, views, description) to the transcript (default).              |
+| `--no-details`          | Suppress video details, transcript only.                                                                       |
+| `--no-decode-entities`  | Preserve raw HTML entities (e.g. `&#39;`). Decoded by default in text mode.                                    |
+| `--help`                | Show help message and exit.                                                                                    |
+| `--version`             | Show version number and exit.                                                                                  |
+
+## JSON format
+
+When `--json` is used, the output is an array of objects:
+
+```json
+[
+  {
+    "text": "♪ We're no strangers to love ♪",
+    "offset": 18.64,
+    "duration": 3.24,
+    "timestamp": "00:18"
+  }
+]
+```
+
+`timestamp` is always present in JSON mode. Video details are suppressed
+(silently) since JSON is structured data.
+
+## Binary
+
+Build a single-file binary with no external dependencies:
+
+```bash
+bun run build
+./dist/prosey dQw4w9WgXcQ
+```
+
+## Development
+
+This project uses **[Bun](https://bun.sh)** for development.
+
+```bash
+bun run typecheck   # TypeScript check
+bun run start       # Run the CLI from source
+bun run test        # Run unit tests
+bun run build       # Compile standalone binary
+```
+
+Before publishing to npm, `bun run build:node` compiles the TypeScript source
+into a Node-compatible JS bundle at `bin/prosey.js`. This happens automatically
+via the `prepack` hook.
+
+## How it works
+
+prosey uses YouTube's Innertube API via the
+[youtube-transcript-plus](https://github.com/ericmmartin/youtube-transcript-plus)
+library. No API keys or browser automation required.
+
+The tool works with both manually created captions and auto-generated
+transcripts (YouTube's speech-to-text). Auto-detection falls through languages
+in the order provided by YouTube's player response.

package/bin/prosey.js

@@ -0,0 +1,604 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { writeFile } from "node:fs/promises";
+
+// node_modules/youtube-transcript-plus/dist/youtube-transcript-plus.mjs
+function __awaiter(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+}
+var DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+var RE_YOUTUBE = /(?:v=|\/|v\/|embed\/|watch\?.*v=|youtu\.be\/|\/v\/|e\/|watch\?.*vi?=|\/embed\/|\/v\/|vi?\/|watch\?.*vi?=|youtu\.be\/|\/vi?\/|\/e\/)([a-zA-Z0-9_-]{11})/i;
+var RE_XML_TRANSCRIPT = /<text start="([^"]*)" dur="([^"]*)">([^<]*)<\/text>/g;
+class YoutubeTranscriptTooManyRequestError extends Error {
+  constructor() {
+    super("YouTube is receiving too many requests from your IP address. Please try again later or use a proxy. If the issue persists, consider reducing the frequency of requests.");
+    this.name = "YoutubeTranscriptTooManyRequestError";
+  }
+}
+
+class YoutubeTranscriptVideoUnavailableError extends Error {
+  constructor(videoId) {
+    super(`The video with ID "${videoId}" is no longer available or has been removed. Please check the video URL or ID and try again.`);
+    this.name = "YoutubeTranscriptVideoUnavailableError";
+    this.videoId = videoId;
+  }
+}
+
+class YoutubeTranscriptDisabledError extends Error {
+  constructor(videoId) {
+    super(`Transcripts are disabled for the video with ID "${videoId}". This may be due to the video owner disabling captions or the video not supporting transcripts.`);
+    this.name = "YoutubeTranscriptDisabledError";
+    this.videoId = videoId;
+  }
+}
+
+class YoutubeTranscriptNotAvailableError extends Error {
+  constructor(videoId) {
+    super(`No transcripts are available for the video with ID "${videoId}". This may be because the video does not have captions or the captions are not accessible.`);
+    this.name = "YoutubeTranscriptNotAvailableError";
+    this.videoId = videoId;
+  }
+}
+
+class YoutubeTranscriptNotAvailableLanguageError extends Error {
+  constructor(lang, availableLangs, videoId) {
+    super(`No transcripts are available in "${lang}" for the video with ID "${videoId}". Available languages: ${availableLangs.join(", ")}. Please try a different language.`);
+    this.name = "YoutubeTranscriptNotAvailableLanguageError";
+    this.videoId = videoId;
+    this.lang = lang;
+    this.availableLangs = availableLangs;
+  }
+}
+
+class YoutubeTranscriptInvalidLangError extends Error {
+  constructor(lang) {
+    super(`Invalid language code "${lang}". Please provide a valid BCP 47 language code (e.g., "en", "fr", "pt-BR").`);
+    this.name = "YoutubeTranscriptInvalidLangError";
+    this.lang = lang;
+  }
+}
+
+class YoutubeTranscriptInvalidVideoIdError extends Error {
+  constructor() {
+    super('Invalid YouTube video ID or URL. Please provide a valid video ID or URL. Example: "dQw4w9WgXcQ" or "https://www.youtube.com/watch?v=dQw4w9WgXcQ".');
+    this.name = "YoutubeTranscriptInvalidVideoIdError";
+  }
+}
+var RE_VIDEO_ID = /^[a-zA-Z0-9_-]{11}$/;
+var RE_BCP47_LANG = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+var XML_ENTITIES = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&apos;": "'"
+};
+var RE_XML_ENTITY = /&(?:amp|lt|gt|quot|apos|#39);/g;
+function decodeXmlEntities(text) {
+  return text.replace(RE_XML_ENTITY, (match) => {
+    var _a;
+    return (_a = XML_ENTITIES[match]) !== null && _a !== undefined ? _a : match;
+  });
+}
+function retrieveVideoId(videoId) {
+  if (RE_VIDEO_ID.test(videoId)) {
+    return videoId;
+  }
+  const matchId = videoId.match(RE_YOUTUBE);
+  if (matchId && matchId.length) {
+    return matchId[1];
+  }
+  throw new YoutubeTranscriptInvalidVideoIdError;
+}
+function validateLang(lang) {
+  if (!RE_BCP47_LANG.test(lang)) {
+    throw new YoutubeTranscriptInvalidLangError(lang);
+  }
+}
+function defaultFetch(params) {
+  return __awaiter(this, undefined, undefined, function* () {
+    const { url, lang, userAgent, method = "GET", body, headers = {}, signal } = params;
+    const fetchHeaders = Object.assign(Object.assign({ "User-Agent": userAgent || DEFAULT_USER_AGENT }, lang && { "Accept-Language": lang }), headers);
+    const fetchOptions = {
+      method,
+      headers: fetchHeaders,
+      signal
+    };
+    if (body && method === "POST") {
+      fetchOptions.body = body;
+    }
+    return fetch(url, fetchOptions);
+  });
+}
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    signal === null || signal === undefined || signal.throwIfAborted();
+    const timer = setTimeout(resolve, ms);
+    if (signal) {
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function fetchWithRetry(fetchFn, retries, retryDelay, signal) {
+  return __awaiter(this, undefined, undefined, function* () {
+    for (let attempt = 0;attempt <= retries; attempt++) {
+      signal === null || signal === undefined || signal.throwIfAborted();
+      const response = yield fetchFn();
+      if (!isRetryableStatus(response.status) || attempt === retries) {
+        return response;
+      }
+      const delay = retryDelay * Math.pow(2, attempt);
+      yield sleep(delay, signal);
+    }
+    throw new Error("Unexpected: retry loop exited without returning");
+  });
+}
+class YoutubeTranscript {
+  constructor(config) {
+    this.config = config;
+  }
+  _fetchCaptionTracks(identifier, lang) {
+    return __awaiter(this, undefined, undefined, function* () {
+      var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+      const userAgent = (_b = (_a = this.config) === null || _a === undefined ? undefined : _a.userAgent) !== null && _b !== undefined ? _b : DEFAULT_USER_AGENT;
+      const protocol = ((_c = this.config) === null || _c === undefined ? undefined : _c.disableHttps) ? "http" : "https";
+      const retries = (_e = (_d = this.config) === null || _d === undefined ? undefined : _d.retries) !== null && _e !== undefined ? _e : 0;
+      const retryDelay = (_g = (_f = this.config) === null || _f === undefined ? undefined : _f.retryDelay) !== null && _g !== undefined ? _g : 1000;
+      const signal = (_h = this.config) === null || _h === undefined ? undefined : _h.signal;
+      const watchUrl = `${protocol}://www.youtube.com/watch?v=${identifier}`;
+      const watchFetchParams = { url: watchUrl, lang, userAgent, signal };
+      const videoPageResponse = yield fetchWithRetry(() => {
+        var _a2;
+        return ((_a2 = this.config) === null || _a2 === undefined ? undefined : _a2.videoFetch) ? this.config.videoFetch(watchFetchParams) : defaultFetch(watchFetchParams);
+      }, retries, retryDelay, signal);
+      if (!videoPageResponse.ok) {
+        throw new YoutubeTranscriptVideoUnavailableError(identifier);
+      }
+      const videoPageBody = yield videoPageResponse.text();
+      if (videoPageBody.includes('class="g-recaptcha"')) {
+        throw new YoutubeTranscriptTooManyRequestError;
+      }
+      const apiKeyMatch = videoPageBody.match(/"INNERTUBE_API_KEY":"([^"]+)"/) || videoPageBody.match(/INNERTUBE_API_KEY\\":\\"([^\\"]+)\\"/);
+      if (!apiKeyMatch) {
+        throw new YoutubeTranscriptNotAvailableError(identifier);
+      }
+      const apiKey = apiKeyMatch[1];
+      const playerEndpoint = `${protocol}://www.youtube.com/youtubei/v1/player?key=${apiKey}`;
+      const playerBody = {
+        context: {
+          client: {
+            clientName: "ANDROID",
+            clientVersion: "20.10.38"
+          }
+        },
+        videoId: identifier
+      };
+      const playerFetchParams = {
+        url: playerEndpoint,
+        method: "POST",
+        lang,
+        userAgent,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(playerBody),
+        signal
+      };
+      const playerRes = yield fetchWithRetry(() => {
+        var _a2;
+        return ((_a2 = this.config) === null || _a2 === undefined ? undefined : _a2.playerFetch) ? this.config.playerFetch(playerFetchParams) : defaultFetch(playerFetchParams);
+      }, retries, retryDelay, signal);
+      if (!playerRes.ok) {
+        throw new YoutubeTranscriptVideoUnavailableError(identifier);
+      }
+      const playerJson = yield playerRes.json();
+      const tracklist = (_k = (_j = playerJson.captions) === null || _j === undefined ? undefined : _j.playerCaptionsTracklistRenderer) !== null && _k !== undefined ? _k : playerJson.playerCaptionsTracklistRenderer;
+      const tracks = tracklist === null || tracklist === undefined ? undefined : tracklist.captionTracks;
+      const isPlayableOk = ((_l = playerJson.playabilityStatus) === null || _l === undefined ? undefined : _l.status) === "OK";
+      if (!playerJson.captions || !tracklist) {
+        if (isPlayableOk) {
+          throw new YoutubeTranscriptDisabledError(identifier);
+        }
+        throw new YoutubeTranscriptNotAvailableError(identifier);
+      }
+      if (!Array.isArray(tracks) || tracks.length === 0) {
+        throw new YoutubeTranscriptDisabledError(identifier);
+      }
+      return { tracks, playerJson };
+    });
+  }
+  _extractVideoDetails(playerJson, identifier) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const raw = playerJson.videoDetails;
+    return {
+      videoId: (_a = raw === null || raw === undefined ? undefined : raw.videoId) !== null && _a !== undefined ? _a : identifier,
+      title: (_b = raw === null || raw === undefined ? undefined : raw.title) !== null && _b !== undefined ? _b : "",
+      author: (_c = raw === null || raw === undefined ? undefined : raw.author) !== null && _c !== undefined ? _c : "",
+      channelId: (_d = raw === null || raw === undefined ? undefined : raw.channelId) !== null && _d !== undefined ? _d : "",
+      lengthSeconds: parseInt((_e = raw === null || raw === undefined ? undefined : raw.lengthSeconds) !== null && _e !== undefined ? _e : "0", 10),
+      viewCount: parseInt((_f = raw === null || raw === undefined ? undefined : raw.viewCount) !== null && _f !== undefined ? _f : "0", 10),
+      description: (_g = raw === null || raw === undefined ? undefined : raw.shortDescription) !== null && _g !== undefined ? _g : "",
+      keywords: (_h = raw === null || raw === undefined ? undefined : raw.keywords) !== null && _h !== undefined ? _h : [],
+      thumbnails: (_k = (_j = raw === null || raw === undefined ? undefined : raw.thumbnail) === null || _j === undefined ? undefined : _j.thumbnails) !== null && _k !== undefined ? _k : [],
+      isLiveContent: (_l = raw === null || raw === undefined ? undefined : raw.isLiveContent) !== null && _l !== undefined ? _l : false
+    };
+  }
+  fetchTranscript(videoId) {
+    return __awaiter(this, undefined, undefined, function* () {
+      var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+      const identifier = retrieveVideoId(videoId);
+      const lang = (_a = this.config) === null || _a === undefined ? undefined : _a.lang;
+      if (lang) {
+        validateLang(lang);
+      }
+      const userAgent = (_c = (_b = this.config) === null || _b === undefined ? undefined : _b.userAgent) !== null && _c !== undefined ? _c : DEFAULT_USER_AGENT;
+      const includeDetails = ((_d = this.config) === null || _d === undefined ? undefined : _d.videoDetails) === true;
+      const cache = (_e = this.config) === null || _e === undefined ? undefined : _e.cache;
+      const cacheTTL = (_f = this.config) === null || _f === undefined ? undefined : _f.cacheTTL;
+      const cacheKey = includeDetails ? `yt:transcript+details:${identifier}:${lang !== null && lang !== undefined ? lang : ""}` : `yt:transcript:${identifier}:${lang !== null && lang !== undefined ? lang : ""}`;
+      if (cache) {
+        const cached = yield cache.get(cacheKey);
+        if (cached) {
+          try {
+            return JSON.parse(cached);
+          } catch (_p) {}
+        }
+      }
+      const { tracks, playerJson } = yield this._fetchCaptionTracks(identifier, lang);
+      const selectedTrack = lang ? tracks.find((t) => t.languageCode === lang) : tracks[0];
+      if (!selectedTrack) {
+        const available = tracks.map((t) => t.languageCode).filter(Boolean);
+        throw new YoutubeTranscriptNotAvailableLanguageError(lang, available, identifier);
+      }
+      const transcriptBaseURL = (_g = selectedTrack.baseUrl) !== null && _g !== undefined ? _g : selectedTrack.url;
+      if (!transcriptBaseURL) {
+        throw new YoutubeTranscriptNotAvailableError(identifier);
+      }
+      let transcriptURL = transcriptBaseURL;
+      transcriptURL = transcriptURL.replace(/&fmt=[^&]+/, "");
+      if ((_h = this.config) === null || _h === undefined ? undefined : _h.disableHttps) {
+        transcriptURL = transcriptURL.replace(/^https:\/\//, "http://");
+      }
+      const retries = (_k = (_j = this.config) === null || _j === undefined ? undefined : _j.retries) !== null && _k !== undefined ? _k : 0;
+      const retryDelay = (_m = (_l = this.config) === null || _l === undefined ? undefined : _l.retryDelay) !== null && _m !== undefined ? _m : 1000;
+      const signal = (_o = this.config) === null || _o === undefined ? undefined : _o.signal;
+      const transcriptFetchParams = { url: transcriptURL, lang, userAgent, signal };
+      const transcriptResponse = yield fetchWithRetry(() => {
+        var _a2;
+        return ((_a2 = this.config) === null || _a2 === undefined ? undefined : _a2.transcriptFetch) ? this.config.transcriptFetch(transcriptFetchParams) : defaultFetch(transcriptFetchParams);
+      }, retries, retryDelay, signal);
+      if (!transcriptResponse.ok) {
+        if (transcriptResponse.status === 429) {
+          throw new YoutubeTranscriptTooManyRequestError;
+        }
+        throw new YoutubeTranscriptNotAvailableError(identifier);
+      }
+      const transcriptBody = yield transcriptResponse.text();
+      const results = [...transcriptBody.matchAll(RE_XML_TRANSCRIPT)];
+      const segments = results.map((m) => ({
+        text: decodeXmlEntities(m[3]),
+        duration: parseFloat(m[2]),
+        offset: parseFloat(m[1]),
+        lang: lang !== null && lang !== undefined ? lang : selectedTrack.languageCode
+      }));
+      if (segments.length === 0) {
+        throw new YoutubeTranscriptNotAvailableError(identifier);
+      }
+      const result = includeDetails ? { videoDetails: this._extractVideoDetails(playerJson, identifier), segments } : segments;
+      if (cache) {
+        try {
+          yield cache.set(cacheKey, JSON.stringify(result), cacheTTL);
+        } catch (_q) {}
+      }
+      return result;
+    });
+  }
+  listLanguages(videoId) {
+    return __awaiter(this, undefined, undefined, function* () {
+      const identifier = retrieveVideoId(videoId);
+      const { tracks } = yield this._fetchCaptionTracks(identifier);
+      return tracks.map((track) => {
+        var _a, _b;
+        return {
+          languageCode: track.languageCode,
+          languageName: (_b = (_a = track.name) === null || _a === undefined ? undefined : _a.simpleText) !== null && _b !== undefined ? _b : track.languageCode,
+          isAutoGenerated: track.kind === "asr"
+        };
+      });
+    });
+  }
+  static fetchTranscript(videoId, config) {
+    return __awaiter(this, undefined, undefined, function* () {
+      const instance = new YoutubeTranscript(config);
+      return instance.fetchTranscript(videoId);
+    });
+  }
+  static listLanguages(videoId, config) {
+    return __awaiter(this, undefined, undefined, function* () {
+      const instance = new YoutubeTranscript(config);
+      return instance.listLanguages(videoId);
+    });
+  }
+}
+function fetchTranscript(videoId, config) {
+  return YoutubeTranscript.fetchTranscript(videoId, config);
+}
+var listLanguages = YoutubeTranscript.listLanguages;
+
+// src/format.ts
+var namedEntities = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'"
+};
+function formatTime(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = Math.floor(seconds % 60);
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+function formatDuration(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = Math.floor(seconds % 60);
+  if (h > 0) {
+    return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+  }
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+function decodeEntities(text) {
+  return text.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code))).replace(/&(\w+);/g, (_, name) => namedEntities[name] ?? `&${name};`);
+}
+function formatWithTimestamps(segments, decode) {
+  return segments.map((s) => {
+    const text = decode ? decodeEntities(s.text) : s.text;
+    return `[${formatTime(s.offset)}] ${text}`;
+  }).join(`
+`);
+}
+function toText(segments, decode) {
+  return segments.map((s) => decode ? decodeEntities(s.text) : s.text).join(" ").replace(/ +/g, " ");
+}
+function toJSON(segments, decode) {
+  const data = segments.map((s) => ({
+    text: decode ? decodeEntities(s.text) : s.text,
+    offset: s.offset,
+    duration: s.duration,
+    timestamp: formatTime(s.offset)
+  }));
+  return JSON.stringify(data, null, 2);
+}
+
+// src/index.ts
+var NAME = "prosey";
+var VERSION = "0.1.0";
+function help() {
+  return `${NAME} v${VERSION}
+
+Usage: ${NAME} [options] <video-url-or-id>
+       ${NAME} info [options] <video-url-or-id>
+
+Download a YouTube video transcript or show video details.
+
+Commands:
+  info                  Show video metadata (title, channel, duration, etc.)
+
+Arguments:
+  video-url-or-id        YouTube URL (full or short) or bare video ID
+
+Options:
+  --lang <code>          Language code (e.g. en, fr). Auto-detect if omitted.
+  -t, --timestamps       Include timestamps [MM:SS] in output.
+  --list                 List available transcript languages and exit.
+  -o, --output <path>    Write output to file instead of stdout.
+  --json                 Output as JSON (suppresses details).
+  --text                 Output as plain text (default).
+  --details              Prepend video details to transcript (default, text only).
+  --no-details           Suppress video details, transcript only.
+  --no-decode-entities   Preserve HTML entities (decoded by default).
+  --help                 Show this help message.
+  --version              Show version.
+
+Examples:
+  ${NAME} dQw4w9WgXcQ
+  ${NAME} https://www.youtube.com/watch?v=dQw4w9WgXcQ --lang es
+  ${NAME} dQw4w9WgXcQ -t -o transcript.txt
+  ${NAME} dQw4w9WgXcQ --list
+  ${NAME} dQw4w9WgXcQ --json
+  ${NAME} dQw4w9WgXcQ --no-details
+  ${NAME} info dQw4w9WgXcQ`;
+}
+function formatDetailsBlock(details) {
+  const lines = [
+    `Title:    ${decodeEntities(details.title)}`,
+    `Channel:  ${details.author}`,
+    `Duration: ${formatDuration(details.lengthSeconds)}`,
+    `Views:    ${details.viewCount.toLocaleString()}`
+  ];
+  if (details.description) {
+    const desc = details.description.length > 500 ? details.description.slice(0, 500) + "…" : details.description;
+    lines.push(`Description:
+  ${desc.replace(/\n/g, `
+  `)}`);
+  }
+  return lines.join(`
+`);
+}
+function printVideoInfo(details) {
+  const w = Math.max("Title:".length, "Channel:".length, "Duration:".length, "Views:".length, "Video ID:".length, "Channel ID:".length, "Keywords:".length, "Description:".length);
+  const pad = (s) => s.padEnd(w);
+  const lines = [
+    `${pad("Title:")}      ${decodeEntities(details.title)}`,
+    `${pad("Channel:")}    ${details.author}`,
+    `${pad("Duration:")}   ${formatDuration(details.lengthSeconds)}`,
+    `${pad("Views:")}      ${details.viewCount.toLocaleString()}`,
+    `${pad("Video ID:")}   ${details.videoId}`,
+    `${pad("Channel ID:")} ${details.channelId}`
+  ];
+  if (details.keywords.length > 0) {
+    lines.push(`${pad("Keywords:")}   ${details.keywords.join(", ")}`);
+  }
+  if (details.description) {
+    lines.push(`${pad("Description:")}`);
+    const descLines = details.description.split(`
+`).filter(Boolean);
+    for (const line of descLines) {
+      lines.push(`  ${line}`);
+    }
+  }
+  console.log(lines.join(`
+`));
+}
+function printLanguages(languages) {
+  const rows = languages.map((l) => {
+    const auto = l.isAutoGenerated ? " (auto-generated)" : "";
+    return `  ${l.languageCode.padEnd(8)}${l.languageName}${auto}`;
+  });
+  console.log(`Available transcripts (${languages.length}):
+${rows.join(`
+`)}`);
+}
+var args = process.argv.slice(2);
+if (args.length === 0 || args.includes("--help")) {
+  console.log(help());
+  process.exit(0);
+}
+if (args.includes("--version")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+var mode = "transcript";
+if (args[0] === "info") {
+  mode = "info";
+  args.splice(0, 1);
+}
+var videoId = "";
+var lang;
+var timestamps = false;
+var listOnly = false;
+var outputPath;
+var outputJson = false;
+var noDecode = false;
+var showDetails = true;
+for (let i = 0;i < args.length; i++) {
+  const arg = args[i];
+  if (!arg)
+    continue;
+  if (arg === "--lang") {
+    lang = args[++i] ?? undefined;
+    if (!lang) {
+      console.error("Error: --lang requires a language code");
+      process.exit(1);
+    }
+  } else if (arg === "--timestamps" || arg === "-t") {
+    timestamps = true;
+  } else if (arg === "--list") {
+    listOnly = true;
+  } else if (arg === "-o" || arg === "--output") {
+    outputPath = args[++i] ?? undefined;
+    if (!outputPath) {
+      console.error("Error: -o/--output requires a file path");
+      process.exit(1);
+    }
+  } else if (arg === "--json") {
+    outputJson = true;
+  } else if (arg === "--text") {
+    outputJson = false;
+  } else if (arg === "--details") {
+    showDetails = true;
+  } else if (arg === "--no-details") {
+    showDetails = false;
+  } else if (arg === "--no-decode-entities") {
+    noDecode = true;
+  } else if (arg.startsWith("-")) {
+    console.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  } else {
+    videoId = arg;
+  }
+}
+if (!videoId) {
+  console.error("Error: missing video URL or ID");
+  console.log(help());
+  process.exit(1);
+}
+try {
+  if (mode === "info") {
+    const result = await fetchTranscript(videoId, { videoDetails: true, lang });
+    if (outputJson) {
+      console.log(JSON.stringify(result.videoDetails, null, 2));
+    } else {
+      printVideoInfo(result.videoDetails);
+    }
+    process.exit(0);
+  }
+  if (listOnly) {
+    const languages = await listLanguages(videoId);
+    printLanguages(languages);
+    process.exit(0);
+  }
+  const decode = !noDecode;
+  if (showDetails && !outputJson) {
+    const config = lang ? { lang, videoDetails: true } : { videoDetails: true };
+    const result = await fetchTranscript(videoId, config);
+    const detailsBlock = formatDetailsBlock(result.videoDetails);
+    const transcript = timestamps ? formatWithTimestamps(result.segments, decode) : toText(result.segments, decode);
+    const output = detailsBlock + `
+
+
+` + transcript + `
+`;
+    if (outputPath) {
+      await writeFile(outputPath, output, "utf8");
+    } else {
+      console.log(output);
+    }
+  } else {
+    const segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
+    const output = outputJson ? toJSON(segments, decode) + `
+` : timestamps ? formatWithTimestamps(segments, decode) + `
+` : toText(segments, decode) + `
+`;
+    if (outputPath) {
+      await writeFile(outputPath, output, "utf8");
+    } else {
+      console.log(output);
+    }
+  }
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tacone/prosey",
+  "version": "0.1.0",
+  "description": "Download YouTube video transcripts from the CLI",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "prosey": "bin/prosey.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile dist/prosey",
+    "build:node": "bun build src/index.ts --target node --outfile bin/prosey.js",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prettier": "prettier --write .",
+    "prepack": "bun run build:node",
+    "prepare": "husky || true"
+  },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown"
+  },
+  "author": "tacone <tacone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tacone/prosey.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tacone/prosey/issues"
+  },
+  "homepage": "https://github.com/tacone/prosey#readme",
+  "keywords": [
+    "youtube",
+    "transcript",
+    "subtitles",
+    "captions",
+    "cli",
+    "npx",
+    "bun"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.7",
+    "prettier": "^3.8.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "youtube-transcript-plus": "^2.0.0"
+  }
+}

package/src/format.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import type { TranscriptSegment } from "youtube-transcript-plus";
+import { formatTime, decodeEntities, formatWithTimestamps, toText, toJSON } from "./format";
+
+const segments: TranscriptSegment[] = [
+  { text: "Hello world", offset: 1.5, duration: 2.0, lang: "en" },
+  { text: "This is 'text'", offset: 10, duration: 3.0, lang: "en" },
+  { text: "Line three", offset: 60, duration: 5.0, lang: "en" },
+];
+
+describe("formatTime", () => {
+  test("zero", () => expect(formatTime(0)).toBe("00:00"));
+  test("seconds only", () => expect(formatTime(5)).toBe("00:05"));
+  test("minute boundary", () => expect(formatTime(60)).toBe("01:00"));
+  test("minutes and seconds", () => expect(formatTime(65)).toBe("01:05"));
+  test("long duration", () => expect(formatTime(3661)).toBe("61:01"));
+  test("fractional truncated", () => expect(formatTime(90.7)).toBe("01:30"));
+});
+
+describe("decodeEntities", () => {
+  test("plain text unchanged", () => expect(decodeEntities("hello")).toBe("hello"));
+  test("apostrophe", () => expect(decodeEntities("'")).toBe("'"));
+  test("ampersand", () => expect(decodeEntities("&")).toBe("&"));
+  test("multiple entities", () =>
+    expect(decodeEntities("'hello' & 'world'")).toBe("'hello' & 'world'"));
+  test("numeric entity", () => expect(decodeEntities("&")).toBe("&"));
+});
+
+describe("formatWithTimestamps", () => {
+  test("includes timestamps and decodes by default", () => {
+    const result = formatWithTimestamps(segments, true);
+    expect(result).toBe("[00:01] Hello world\n[00:10] This is 'text'\n[01:00] Line three");
+  });
+
+  test("skips decoding when false", () => {
+    const result = formatWithTimestamps(segments, false);
+    expect(result).toBe("[00:01] Hello world\n[00:10] This is 'text'\n[01:00] Line three");
+  });
+});
+
+describe("toText", () => {
+  test("joins segments with space and decodes", () => {
+    const result = toText(segments, true);
+    expect(result).toBe("Hello world This is 'text' Line three");
+  });
+
+  test("skips decoding when false", () => {
+    const result = toText(segments, false);
+    expect(result).toBe("Hello world This is 'text' Line three");
+  });
+});
+
+describe("toJSON", () => {
+  test("includes all fields and always has timestamp", () => {
+    const result = JSON.parse(toJSON(segments, true));
+    expect(result).toHaveLength(3);
+    expect(result[0]).toEqual({
+      text: "Hello world",
+      offset: 1.5,
+      duration: 2.0,
+      timestamp: "00:01",
+    });
+  });
+
+  test("decodes entities by default", () => {
+    const result = JSON.parse(toJSON(segments, true));
+    expect(result[1].text).toBe("This is 'text'");
+  });
+
+  test("preserves entities when decode is false", () => {
+    const result = JSON.parse(toJSON(segments, false));
+    expect(result[1].text).toBe("This is 'text'");
+  });
+});

package/src/format.ts

@@ -0,0 +1,57 @@
+import type { TranscriptSegment } from "youtube-transcript-plus";
+
+const namedEntities: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+};
+
+export function formatTime(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = Math.floor(seconds % 60);
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+
+export function formatDuration(seconds: number): string {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  if (h > 0) {
+    return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+  }
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+
+export function decodeEntities(text: string): string {
+  return text
+    .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+    .replace(/&(\w+);/g, (_, name) => namedEntities[name] ?? `&${name};`);
+}
+
+export function formatWithTimestamps(segments: TranscriptSegment[], decode: boolean): string {
+  return segments
+    .map((s) => {
+      const text = decode ? decodeEntities(s.text) : s.text;
+      return `[${formatTime(s.offset)}] ${text}`;
+    })
+    .join("\n");
+}
+
+export function toText(segments: TranscriptSegment[], decode: boolean): string {
+  return segments
+    .map((s) => (decode ? decodeEntities(s.text) : s.text))
+    .join(" ")
+    .replace(/ +/g, " ");
+}
+
+export function toJSON(segments: TranscriptSegment[], decode: boolean): string {
+  const data = segments.map((s) => ({
+    text: decode ? decodeEntities(s.text) : s.text,
+    offset: s.offset,
+    duration: s.duration,
+    timestamp: formatTime(s.offset),
+  }));
+  return JSON.stringify(data, null, 2);
+}

package/src/index.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+import { writeFile } from "node:fs/promises";
+import { fetchTranscript, listLanguages } from "youtube-transcript-plus";
+import type { CaptionTrackInfo, VideoDetails } from "youtube-transcript-plus";
+import { formatWithTimestamps, toText, toJSON, formatDuration, decodeEntities } from "./format";
+
+const NAME = "prosey";
+const VERSION = "0.1.0";
+
+function help(): string {
+  return `${NAME} v${VERSION}
+
+Usage: ${NAME} [options] <video-url-or-id>
+       ${NAME} info [options] <video-url-or-id>
+
+Download a YouTube video transcript or show video details.
+
+Commands:
+  info                  Show video metadata (title, channel, duration, etc.)
+
+Arguments:
+  video-url-or-id        YouTube URL (full or short) or bare video ID
+
+Options:
+  --lang <code>          Language code (e.g. en, fr). Auto-detect if omitted.
+  -t, --timestamps       Include timestamps [MM:SS] in output.
+  --list                 List available transcript languages and exit.
+  -o, --output <path>    Write output to file instead of stdout.
+  --json                 Output as JSON (suppresses details).
+  --text                 Output as plain text (default).
+  --details              Prepend video details to transcript (default, text only).
+  --no-details           Suppress video details, transcript only.
+  --no-decode-entities   Preserve HTML entities (decoded by default).
+  --help                 Show this help message.
+  --version              Show version.
+
+Examples:
+  ${NAME} dQw4w9WgXcQ
+  ${NAME} https://www.youtube.com/watch?v=dQw4w9WgXcQ --lang es
+  ${NAME} dQw4w9WgXcQ -t -o transcript.txt
+  ${NAME} dQw4w9WgXcQ --list
+  ${NAME} dQw4w9WgXcQ --json
+  ${NAME} dQw4w9WgXcQ --no-details
+  ${NAME} info dQw4w9WgXcQ`;
+}
+
+function formatDetailsBlock(details: VideoDetails): string {
+  const lines: string[] = [
+    `Title:    ${decodeEntities(details.title)}`,
+    `Channel:  ${details.author}`,
+    `Duration: ${formatDuration(details.lengthSeconds)}`,
+    `Views:    ${details.viewCount.toLocaleString()}`,
+  ];
+
+  if (details.description) {
+    const desc =
+      details.description.length > 500
+        ? details.description.slice(0, 500) + "…"
+        : details.description;
+    lines.push(`Description:\n  ${desc.replace(/\n/g, "\n  ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+function printVideoInfo(details: VideoDetails): void {
+  const w = Math.max(
+    "Title:".length,
+    "Channel:".length,
+    "Duration:".length,
+    "Views:".length,
+    "Video ID:".length,
+    "Channel ID:".length,
+    "Keywords:".length,
+    "Description:".length,
+  );
+  const pad = (s: string) => s.padEnd(w);
+
+  const lines: string[] = [
+    `${pad("Title:")}      ${decodeEntities(details.title)}`,
+    `${pad("Channel:")}    ${details.author}`,
+    `${pad("Duration:")}   ${formatDuration(details.lengthSeconds)}`,
+    `${pad("Views:")}      ${details.viewCount.toLocaleString()}`,
+    `${pad("Video ID:")}   ${details.videoId}`,
+    `${pad("Channel ID:")} ${details.channelId}`,
+  ];
+
+  if (details.keywords.length > 0) {
+    lines.push(`${pad("Keywords:")}   ${details.keywords.join(", ")}`);
+  }
+
+  if (details.description) {
+    lines.push(`${pad("Description:")}`);
+    const descLines = details.description.split("\n").filter(Boolean);
+    for (const line of descLines) {
+      lines.push(`  ${line}`);
+    }
+  }
+
+  console.log(lines.join("\n"));
+}
+
+function printLanguages(languages: CaptionTrackInfo[]): void {
+  const rows = languages.map((l) => {
+    const auto = l.isAutoGenerated ? " (auto-generated)" : "";
+    return `  ${l.languageCode.padEnd(8)}${l.languageName}${auto}`;
+  });
+  console.log(`Available transcripts (${languages.length}):\n${rows.join("\n")}`);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes("--help")) {
+  console.log(help());
+  process.exit(0);
+}
+
+if (args.includes("--version")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+let mode = "transcript";
+if (args[0] === "info") {
+  mode = "info";
+  args.splice(0, 1);
+}
+
+let videoId = "";
+let lang: string | undefined;
+let timestamps = false;
+let listOnly = false;
+let outputPath: string | undefined;
+let outputJson = false;
+let noDecode = false;
+let showDetails = true;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (!arg) continue;
+  if (arg === "--lang") {
+    lang = args[++i] ?? undefined;
+    if (!lang) {
+      console.error("Error: --lang requires a language code");
+      process.exit(1);
+    }
+  } else if (arg === "--timestamps" || arg === "-t") {
+    timestamps = true;
+  } else if (arg === "--list") {
+    listOnly = true;
+  } else if (arg === "-o" || arg === "--output") {
+    outputPath = args[++i] ?? undefined;
+    if (!outputPath) {
+      console.error("Error: -o/--output requires a file path");
+      process.exit(1);
+    }
+  } else if (arg === "--json") {
+    outputJson = true;
+  } else if (arg === "--text") {
+    outputJson = false;
+  } else if (arg === "--details") {
+    showDetails = true;
+  } else if (arg === "--no-details") {
+    showDetails = false;
+  } else if (arg === "--no-decode-entities") {
+    noDecode = true;
+  } else if (arg.startsWith("-")) {
+    console.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  } else {
+    videoId = arg;
+  }
+}
+
+if (!videoId) {
+  console.error("Error: missing video URL or ID");
+  console.log(help());
+  process.exit(1);
+}
+
+try {
+  if (mode === "info") {
+    const result = await fetchTranscript(videoId, { videoDetails: true, lang } as any);
+    if (outputJson) {
+      console.log(JSON.stringify(result.videoDetails, null, 2));
+    } else {
+      printVideoInfo(result.videoDetails);
+    }
+    process.exit(0);
+  }
+
+  if (listOnly) {
+    const languages = await listLanguages(videoId);
+    printLanguages(languages);
+    process.exit(0);
+  }
+
+  const decode = !noDecode;
+
+  if (showDetails && !outputJson) {
+    const config = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
+    const result = (await fetchTranscript(videoId, config)) as {
+      videoDetails: VideoDetails;
+      segments: { text: string; offset: number; duration: number; lang: string }[];
+    };
+    const detailsBlock = formatDetailsBlock(result.videoDetails);
+    const transcript = timestamps
+      ? formatWithTimestamps(result.segments, decode)
+      : toText(result.segments, decode);
+    const output = detailsBlock + "\n\n\n" + transcript + "\n";
+
+    if (outputPath) {
+      await writeFile(outputPath, output, "utf8");
+    } else {
+      console.log(output);
+    }
+  } else {
+    const segments = lang
+      ? await fetchTranscript(videoId, { lang })
+      : await fetchTranscript(videoId);
+
+    const output = outputJson
+      ? toJSON(segments, decode) + "\n"
+      : timestamps
+        ? formatWithTimestamps(segments, decode) + "\n"
+        : toText(segments, decode) + "\n";
+
+    if (outputPath) {
+      await writeFile(outputPath, output, "utf8");
+    } else {
+      console.log(output);
+    }
+  }
+} catch (err: unknown) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}