506 lines
35 KiB
Markdown
506 lines
35 KiB
Markdown
# Auditoría · Cómo la extensión obtiene la transcripción / información de vídeos de YouTube
|
||
|
||
> **Producto auditado:** *Obsidian Web Clipper* (Chrome / Chromium / Firefox / Safari) — versión `1.7.1` del paquete `D:\Obsidian Web Clipper - Chrome Web Store 1.7.1.0`.
|
||
> **Tipo de extensión:** MV3 (manifest v3) con service worker (`background.js`).
|
||
> **Alcance de la auditoría:** mecanismo end‑to‑end por el que la extensión extrae metadatos y la transcripción de un vídeo de YouTube (incluye short `youtu.be`, `youtube.com/watch?v=…` y `youtube.com/shorts/…`).
|
||
> **Fecha:** 2026‑07‑26.
|
||
> **Audiencia del documento:** LLMs / agentes de mantenimiento. Estructura deliberadamente declarativa, sin prosa narrativa.
|
||
|
||
---
|
||
|
||
## 0 · TL;DR (resumen ejecutable)
|
||
|
||
1. La extensión **no usa `timedtext`, `youtube-transcript` web, ni scraping de `ytd-transcript-segment-renderer` como ruta principal** cuando la URL es un watch normal: usa la **API privada `youtubei/v1/player`** (InnerTube) con cabeceras que imitan clientes oficiales de YouTube (ANDROID, IOS, WEB).
|
||
2. Para llegar a esa API sin ser bloqueada por CORS / firma, el `service worker` declara una regla `declarativeNetRequest` (id `9002`, nombre interno `enableYouTubeInnertubeRule`) que **fuerza `Origin: https://www.youtube.com` y `Referer: https://www.youtube.com/`** en toda petición XHR iniciada por la propia extensión hacia `||youtube.com/youtubei/`.
|
||
3. La capa de extracción es una clase `YoutubeExtractor` (en `popup.js` y replicada en `reader-page.js`, ambos `webpack` bundles de Defuddle) que:
|
||
- 1️⃣ parsea el JSON embebido `ytInitialPlayerResponse` del DOM para sacar `captionTracks` y `baseUrl` sin red.
|
||
- 2️⃣ si falla, abre el panel "Mostrar transcripción" del propio YouTube haciendo `click()` y espera con `MutationObserver`‑style polling (DOM scraping fallback).
|
||
- 3️⃣ si la transcripción automática no está disponible, llama a `youtubei/v1/player` con 3 identidades de cliente en cascada (ANDROID → IOS → WEB) hasta que una devuelve `captions.playerCaptionsTracklistRenderer.captionTracks`.
|
||
- 4️⃣ descarga la pista (`timedtext`-like `baseUrl` con sufijo `&fmt=…`) y la parsea como XML.
|
||
4. Los capítulos se extraen con una segunda ruta: `youtubei/v1/next` (también con cabeceras de cliente), o desde `ytInitialData` embebido (`playerOverlays.playerOverlayRenderer.decoratedPlayerBarRenderer.multiMarkersPlayerBarRenderer.markersMap`).
|
||
5. Toda la red de la popup se hace con `globalThis.fetch` directo (no hay proxy interno), aprovechando la regla DNR 9002. El background solo ofrece un *fallback* `sendNativeMessage` para hosts que devuelven CORS (por ejemplo Bilibili).
|
||
|
||
---
|
||
|
||
## 1 · Vista general de componentes (mapa de archivos)
|
||
|
||
| Archivo | Rol respecto a YouTube | Tamaño aprox. | Notas |
|
||
|---|---|---|---|
|
||
| `manifest.json` | Declara `host_permissions: ["<all_urls>","http://*/*","https://*/*"]` y `declarativeNetRequest`. | 89 líneas | Sin URL allow‑list específica de YouTube. |
|
||
| `background.js` (service worker) | Define la **regla DNR 9002** `enableYouTubeInnertubeRule` (set Origin/Referer para `||youtube.com/youtubei/`). Contiene además `enableYouTubeEmbedRule` (9001) que pone `Referer: https://obsidian.md/` en iframes `||youtube.com/embed/`. | ~1 archivo compilado | Comentario interno: `initiatorDomains: [chrome.runtime.id]` ⇒ sólo afecta peticiones de la propia extensión. |
|
||
| `content.js` (content script) | Sólo contiene el glue de highlights (`getClosestTextBlock` ignora elementos con clase `transcript-segment` para no romper la selección). **No extrae la transcripción.** | 1 bundle webpack | No realiza llamadas a YouTube. |
|
||
| `popup.js` | Contiene la clase `YoutubeExtractor` real (minificada) y todo el código de extracción. Se carga como `popup.html` y como `side-panel.html` (ver `<script type="module" src="popup.js">`). | ~2.5 MB minificado | Aquí vive toda la lógica de transcripción. |
|
||
| `reader-page.js` | Réplica exacta de los extractores (incluye otra copia de `YoutubeExtractor`). Se usa cuando se abre la URL en modo *Reader* (`reader.html?url=…`). | ~2.5 MB minificado | Mismo binario que popup. |
|
||
| `highlighter.js` | Sólo lógica de resaltado (no relevante para transcripción). | — | — |
|
||
| `reader-script.js` | Inyectado por background con `scripting.executeScript` para modo Reader. | — | — |
|
||
| `_locales/*/messages.json` | i18n; incluye claves `readerTranscripts`, `readerPinPlayer`, `readerHighlightActiveLine` (configuración visual de la transcripción, no de extracción). | — | — |
|
||
| `web_accessible_resources` | Lista `reader.css`, `reader-script.js`, `browser-polyfill.min.js`, `style.css`, `side-panel.html`, `flatten-shadow-dom.js`, `highlighter.css`. | — | `popup.js` **no** está en `web_accessible_resources`; por tanto la extracción no se hace desde un script inyectado en la página, sino desde la propia página de extensión. |
|
||
|
||
### 1.1 Flujo de control (quién llama a quién)
|
||
|
||
```
|
||
[user clicks action / shortcut / context menu]
|
||
└─ background.js (service worker)
|
||
└─ browser.action.openPopup() OR tabs.sendMessage("openPopup")
|
||
└─ popup.html (extension page, chrome-extension://<id>/popup.html)
|
||
└─ popup.js (module)
|
||
├─ Defuddle.parse(doc) ← extractor genérico
|
||
│ └─ para URL que matchea "youtube.com" o "youtu.be"
|
||
│ └─ new YoutubeExtractor(document, url, schemaOrg, options)
|
||
│ └─ extractAsync() ⇒ runExtractor()
|
||
│ ├─ extractTranscriptFromExistingDom() (1ª opción)
|
||
│ ├─ fetchTranscript() (2ª opción: red)
|
||
│ └─ extractTranscriptFromOpenedDom() (3ª opción: click en panel)
|
||
└─ resultado ⇒ variables { transcript, language } ⇒ se inyecta en la nota Markdown
|
||
|
||
(En paralelo, la regla DNR 9002 reescribe Origin/Referer de las XHR
|
||
lanzadas por la propia extensión hacia youtube.com/youtubei/v1/…)
|
||
```
|
||
|
||
> **Punto importante para LLMs:** la extracción de YouTube **no se ejecuta dentro de la página de YouTube** ni desde el content script. Se ejecuta en el contexto privilegiado de la extensión (`chrome-extension://`). La página de YouTube solo aporta el `document` con el HTML actual y, opcionalmente, el JSON embebido en los `<script>`.
|
||
|
||
---
|
||
|
||
## 2 · Punto de entrada: ¿cuándo se invoca la extracción?
|
||
|
||
`background.js` ofrece cuatro formas de abrir la popup, todas convergen al mismo punto:
|
||
|
||
| Acción del usuario | Mensaje / llamada en `background.js` | Destino final |
|
||
|---|---|---|
|
||
| Click en icono de la extensión | `action.onClicked` → `openPopup()` | `popup.html` |
|
||
| Atajo `Ctrl+Shift+O` (`_execute_action`) | `commands.onCommand` → `openPopup()` | `popup.html` |
|
||
| Atajo `Alt+Shift+O` (`quick_clip`) | `commands.onCommand` → `openPopup()` + 500 ms `triggerQuickClip` | `popup.html` |
|
||
| Menú contextual "Save this page" / "Add to highlights" | `contextMenus.onClicked` → `openPopup()` | `popup.html` |
|
||
| Behavior `embedded` | `tabs.sendMessage("toggle-iframe")` → `side-panel.html?context=iframe` | `side-panel.html` |
|
||
|
||
> `side-panel.html` y `popup.html` cargan **el mismo `popup.js`** (`<script type="module" src="popup.js">`). Por tanto, la lógica de YouTube es única y se invoca desde dos contenedores distintos.
|
||
|
||
Cuando la popup se carga, en `popup.js` se hace algo equivalente a:
|
||
|
||
```js
|
||
const defuddle = new Defuddle(document, { url: location.href });
|
||
const result = defuddle.parse(); // extracción síncrona
|
||
const asyncVars = await defuddle.fetchAsyncVariables({ language, fetch }); // asíncrono
|
||
```
|
||
|
||
`Defuddle` consulta su `ExtractorRegistry` (poblado en `ExtractorRegistry.initialize()`); para YouTube registra:
|
||
|
||
```js
|
||
this.register({ patterns: ["youtube.com","youtu.be"], extractor: YoutubeExtractor });
|
||
this.register({ patterns: ["m.youtube.com"], extractor: YoutubeExtractor }); // implícito
|
||
this.register({ patterns: [/youtube\.com\/shorts\//], extractor: YoutubeExtractor });
|
||
```
|
||
|
||
El extractor se instancia con `new YoutubeExtractor(document, url, schemaOrgData, options)`. Las `options` que recibe la popup le inyectan `language` (preferida por el usuario) y un `fetch` opcional; si no se inyecta, usa `globalThis.fetch`.
|
||
|
||
---
|
||
|
||
## 3 · `YoutubeExtractor` (la clase clave) — Anatomía
|
||
|
||
> **Ubicación física del código (minificado):**
|
||
> - En `popup.js`, la clase aparece aproximadamente entre los offsets `382 000`–`405 000` del bundle (texto buscado: `class YoutubeExtractor` o el alias `class A extends o.BaseExtractor`).
|
||
> - En `reader-page.js` es la **misma clase** con nombre `A` (mismo fingerprint de strings `transcript-segment-view-model`, `ytwTranscriptSegmentViewModelTimestamp`, `ytInitialPlayerResponse`).
|
||
> - En origen viene del paquete npm `defuddle` (≥ v0.x) — la extensión lo reempaqueta con webpack.
|
||
|
||
### 3.1 Identidad de cliente (constantes globales)
|
||
|
||
```js
|
||
// constantes a nivel de módulo, dentro del bundle de popup.js / reader-page.js
|
||
const TIMEOUT_MS = 4000; // f = 4e3
|
||
const PLAYER_URL = "https://www.youtube.com/youtubei/v1/player?prettyPrint=false"; // g
|
||
const NEXT_URL = "https://www.youtube.com/youtubei/v1/next?prettyPrint=false"; // usado en fetchChapters
|
||
const ANDROID_UA = "com.google.android.youtube/20.10.38 (Linux; U; Android 14)"; // v, usada en b/x
|
||
|
||
// Contextos de cliente (probados en cascada)
|
||
const ANDROID_CLIENT = { client: { clientName: "ANDROID", clientVersion: "20.10.38" } }; // b / x
|
||
const IOS_CLIENT = { client: { clientName: "IOS", clientVersion: "20.10.3" } }; // y
|
||
const WEB_CLIENT = { client: { clientName: "WEB", clientVersion: "2.20240101.00.00" } }; // w
|
||
```
|
||
|
||
### 3.2 Selectores DOM (definidos como objetos)
|
||
|
||
```js
|
||
const DESKTOP_SELECTORS = {
|
||
segments: "ytd-transcript-segment-renderer",
|
||
timestamp: ".segment-timestamp",
|
||
text: ".segment-text",
|
||
};
|
||
const MOBILE_SELECTORS = {
|
||
segments: "transcript-segment-view-model",
|
||
timestamp: ".ytwTranscriptSegmentViewModelTimestamp",
|
||
text: "span.yt-core-attributed-string",
|
||
chapters: "timeline-chapter-view-model h3",
|
||
};
|
||
```
|
||
|
||
`getTranscriptSelectors(container)` elige uno u otro mirando qué nodos existen. Si no existe ninguno devuelve `undefined` (⇒ no hay transcripción en el DOM todavía).
|
||
|
||
### 3.3 Métodos principales (firmas y propósito)
|
||
|
||
| Método | Tipo | Propósito |
|
||
|---|---|---|
|
||
| `getVideoId()` | síncrono | Devuelve el id de 11 chars. Soporta `youtube.com/watch?v=…`, `youtu.be/…`, `youtube.com/shorts/…`. Cachea en `this._videoId`. |
|
||
| `canExtractAsync()` | síncrono | Devuelve `true` si la URL es de YouTube. |
|
||
| `extractAsync()` | async | Punto de entrada. Cadena: `extractTranscriptFromExistingDom()` → si vacío `fetchTranscript()` → si vacío `extractTranscriptFromOpenedDom()`. Devuelve `{ html, text, languageCode, … }` o `null`. |
|
||
| `extractTranscriptFromExistingDom()` | try/catch | Lee los segmentos si YouTube ya renderizó el panel de transcripción (panel abierto por el usuario o cargado por interacción previa). |
|
||
| `getTranscriptContainer()` | síncrono | Selector: `'ytd-engagement-panel-section-list-renderer[target-id="engagement-panel-searchable-transcript"] #segments-container'`; en `m.youtube.com`: `ytm-macro-markers-list-renderer .ytm-macro-markers-list-container`. |
|
||
| `buildTranscriptFromContainer(container, chapters)` | síncrono | Itera cada segmento, parsea timestamp (`parseTimestamp` acepta `h:mm:ss` o `mm:ss`), agrupa por hablante si detecta patrón (`groupTranscriptSegments` → `groupBySpeaker` o `groupBySentence`), y emite HTML `<p class="transcript-segment">` y texto plano `**HH:MM:SS** · texto`. Llama a `buildTranscript("youtube", groups, chapters)`. |
|
||
| `extractTranscriptFromOpenedDom()` | async | Si el panel no estaba abierto pero el DOM lo permite (`canOpenTranscriptPanel()`: `typeof MutationObserver === "function"`): hace **click programático** en `ytd-video-description-transcript-section-renderer button` (o equivalente mobile), espera el contenedor y re-usa `buildTranscriptFromContainer`. |
|
||
| `openMobileTranscriptPanel()` | async | Variante `m.youtube.com`: clicks en `button[aria-label="Show more"]` → espera `button[aria-label="View all"]` → click → espera segmentos. |
|
||
| `fetchTranscript()` | async | **Ruta de red principal**. Ver §3.4. |
|
||
| `fetchPlayerData(videoId)` | async | POST a `youtubei/v1/player` probando 3 clientes en cascada. Ver §3.4. |
|
||
| `fetchChapters(videoId)` | async | POST a `youtubei/v1/next` (cliente WEB) → extrae capítulos de `playerOverlays…multiMarkersPlayerBarRenderer.markersMap[*].value.chapters[*].chapterRenderer`; fallback a `engagementPanels[*].engagementPanelSectionListRenderer.content.macroMarkersListRenderer.contents[*].macroMarkersListItemRenderer`. Si ya están embebidos en `ytInitialData` no se hace red. |
|
||
| `getValidatedPlayerResponse()` | síncrono | Devuelve el JSON parseado de `ytInitialPlayerResponse` (parseado inline desde el `<script>`) **solo si** su `videoDetails.videoId` o `microformat.playerMicroformatRenderer.externalVideoId` coincide con `getVideoId()`. |
|
||
| `parseInlineJson(varName)` | síncrono | Itera todos los `<script>` del documento, encuentra el primero cuyo `textContent` contiene la variable global, **balancea llaves** manualmente y hace `JSON.parse`. Cachea el resultado en `this.inlineJsonCache` (Map). |
|
||
| `getCaptionTracks(playerResponse)` | síncrono | `playerResponse?.captions?.playerCaptionsTracklistRenderer?.captionTracks` (devuelve `[]` si no es array). |
|
||
| `pickCaptionTrack(tracks)` | síncrono | Si hay `options.language`: prefiere la pista exacta (`code === lang`) ⇒ mismo idioma base (`code.split("-")[0] === lang.split("-")[0]`) ⇒ mismo prefijo de idioma. Filtra `kind === "asr"` (auto‑generadas) si hay manuales. Si no, devuelve la primera no‑`asr`, o una con `languageCode === "en"`, o la primera. |
|
||
| `findPreferredCaptionTrack(tracks, lang)` | síncrono | Igual que el anterior pero con scoring explícito. |
|
||
| `getInlineCaptionTrack()` | síncrono | `getValidatedPlayerResponse()` → `getCaptionTracks()` → `pickCaptionTrack()`. Si hay `baseUrl`, devuelve la pista. |
|
||
| `fetchCaptionXml(track, chaptersPromise)` | async | `fetch(track.baseUrl, { headers: { "User-Agent":"Mozilla/5.0", "Accept-Language": lang } })` con `AbortSignal.timeout(4000)`. Devuelve solo si la URL acaba en `.youtube.com`. Pasa el texto a `parseTranscriptXml`. |
|
||
| `parseTranscriptXml(xml, lang, chapters)` | síncrono | Dos regex: `<p t="N">…<s>…</s>…</p>` (formato nuevo) y `<text start="N">…</text>` (formato legacy). Decodifica entidades (`decodeEntities`). Llama a `groupTranscriptSegments` y `buildTranscript`. |
|
||
| `decodeEntities(str)` | síncrono | Reemplazos para `& < > " ' ' &#xHH; &#NN;`. |
|
||
| `groupTranscriptSegments(segs)` | síncrono | Decide por regex CJK: si hay mezcla CJK/Latín → `groupBySpeaker` (split por `:` al inicio de línea); si no → `groupBySentence`. |
|
||
| `getVideoData()` | síncrono | Lee `<script type="application/ld+json">` buscando un `VideoObject` cuyo `embedUrl`/`url`/`@id` contenga el videoId. Fallback a `meta[property="og:title|og:description|og:image|og:url"]`. |
|
||
| `getChannelNameFromDom()` / `getChannelNameFromPlayerResponse()` | síncrono | `[itemprop="name"]` o `videoDetails.author`/`ownerChannelName`/`microformat.playerMicroformatRenderer.ownerChannelName`. |
|
||
| `getTranscriptLanguageCodeFromDom()` | síncrono | Lee el botón de `yt-sort-filter-sub-menu-renderer` en el footer del panel y compara con `name.simpleText`/`name.runs[].text` de cada caption track. |
|
||
| `getInlineChapters()` | síncrono | Desde `ytInitialData`; valida que el videoId en el JSON coincida con el de la URL; cae a `extractChaptersFromEngagementPanels`. |
|
||
| `buildResult(transcript)` | síncrono | Empaqueta `{ title, author, site:"YouTube", image, published, description }`, añade `transcript` y `language` al `variables`, prepende un `<iframe src="https://www.youtube.com/embed/{id}" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen>`. |
|
||
| `formatDescription(text)` | síncrono | `<p>…</p>` con `escapeHtml` y `<br>` por `\n`. |
|
||
|
||
### 3.4 `fetchTranscript()` — núcleo de la ruta de red
|
||
|
||
```js
|
||
async fetchTranscript() {
|
||
const videoId = this.getVideoId();
|
||
const chapters = this.fetchChapters(videoId); // (a)
|
||
const inlineTrack = this.getInlineCaptionTrack(); // (b) caption del JSON embebido
|
||
const inlineFetch = inlineTrack ? this.fetchCaptionXml(inlineTrack, chapters) : undefined; // (c)
|
||
const playerData = await this.fetchPlayerData(videoId); // (d) red: youtubei/v1/player
|
||
const picked = playerData ? this.pickCaptionTrack(this.getCaptionTracks(playerData)) : undefined;
|
||
const remoteFetch = (picked?.baseUrl && picked.baseUrl !== inlineTrack?.baseUrl)
|
||
? this.fetchCaptionXml(picked, chapters) // (e)
|
||
: undefined;
|
||
return (await remoteFetch) || (await inlineFetch);
|
||
}
|
||
```
|
||
|
||
Y `fetchPlayerData()`:
|
||
|
||
```js
|
||
async fetchPlayerData(videoId) {
|
||
// 1º intento: cliente IOS
|
||
try {
|
||
const r = await this.fetch(PLAYER_URL, {
|
||
method: "POST",
|
||
headers: { "Content-Type":"application/json", ...(lang && {"Accept-Language": lang}) },
|
||
signal: AbortSignal.timeout(TIMEOUT_MS),
|
||
body: JSON.stringify({ context: IOS_CLIENT, videoId })
|
||
});
|
||
if (r.ok) { const t = await r.json(); if (this.getCaptionTracks(t).length) return t; }
|
||
} catch {}
|
||
|
||
// 2º intento: cliente ANDROID con UA
|
||
try {
|
||
const r = await this.fetch(PLAYER_URL, {
|
||
method: "POST",
|
||
headers: { "Content-Type":"application/json", "User-Agent": ANDROID_UA, ...(lang && {"Accept-Language": lang}) },
|
||
signal: AbortSignal.timeout(TIMEOUT_MS),
|
||
body: JSON.stringify({ context: ANDROID_CLIENT, videoId })
|
||
});
|
||
if (r.ok) { const t = await r.json(); if (this.getCaptionTracks(t).length) return t; }
|
||
} catch {}
|
||
|
||
// 3º intento: cliente WEB clásico
|
||
try {
|
||
const r = await this.fetch(PLAYER_URL, {
|
||
method: "POST",
|
||
headers: { "Content-Type":"application/json" },
|
||
signal: AbortSignal.timeout(TIMEOUT_MS),
|
||
body: JSON.stringify({ context: WEB_CLIENT, videoId })
|
||
});
|
||
if (r.ok) { const t = await r.json(); if (this.getCaptionTracks(t).length) return t; }
|
||
} catch {}
|
||
|
||
// 4º fallback: parsear el JSON embebido en el HTML (sin red)
|
||
const inline = this.parseInlineJson("ytInitialPlayerResponse");
|
||
if (this.getCaptionTracks(inline).length) return inline;
|
||
}
|
||
```
|
||
|
||
> **Para LLMs:** los 3 contextos de cliente y el `User-Agent` ANDROID son los mismos que usa `youtube-dl`, `yt-dlp` y la mayoría de librerías no oficiales. Si YouTube empieza a rechazar la firma, el orden de los 3 intentos es lo que hay que tocar; también se puede añadir `TVHTML5_SIMPLY_EMBEDDED_PLAYER` u otros.
|
||
|
||
---
|
||
|
||
## 4 · Mecanismo de bypass de CORS / firma de YouTube
|
||
|
||
YouTube no expone `youtubei/v1/player` con CORS abierto, así que la extensión necesita que las peticiones se *vean* como originadas desde la propia web de YouTube. Hay **dos piezas** que lo permiten:
|
||
|
||
### 4.1 `enableYouTubeInnertubeRule` (DNR id `9002`)
|
||
|
||
En `background.js` (en la función `initialize()`):
|
||
|
||
```js
|
||
await dnr.updateSessionRules({
|
||
removeRuleIds: [9002],
|
||
addRules: [{
|
||
id: 9002,
|
||
priority: 1,
|
||
action: {
|
||
type: "modifyHeaders",
|
||
requestHeaders: [
|
||
{ header: "Origin", operation: "set", value: "https://www.youtube.com" },
|
||
{ header: "Referer", operation: "set", value: "https://www.youtube.com/" }
|
||
]
|
||
},
|
||
condition: {
|
||
urlFilter: "||youtube.com/youtubei/",
|
||
resourceTypes: ["xmlhttprequest"],
|
||
initiatorDomains: [ chrome.runtime.id ].filter(Boolean)
|
||
}
|
||
}]
|
||
});
|
||
```
|
||
|
||
> Como el popup (`chrome-extension://<id>/popup.html`) lanza `fetch` desde el contexto de la extensión, el `initiator` de la petición es el `extension_id` ⇒ la regla **solo** se aplica a las peticiones que dispara la propia extensión. Las peticiones que haga el content script de la página de YouTube no se tocan aquí.
|
||
|
||
### 4.2 `webRequest.onBeforeSendHeaders` (sólo Firefox / WebExtensions)
|
||
|
||
En `background.js` también hay (entre `try { … } catch {}` para tolerancia a Safari):
|
||
|
||
```js
|
||
browser_polyfill.webRequest.onBeforeSendHeaders.addListener(details => {
|
||
if (details.tabId > 0) {
|
||
const refHeader = details.requestHeaders.find(h => h.name.toLowerCase() === "referer");
|
||
const refValue = refHeader?.value || "";
|
||
const originHdr = details.requestHeaders.find(h => h.name.toLowerCase() === "origin");
|
||
const originValue = originHdr?.value || "";
|
||
if (!(refValue.startsWith("moz-extension://") || refValue.startsWith("safari-web-extension://"))) {
|
||
return { requestHeaders: details.requestHeaders }; // no tocar: es la propia web
|
||
}
|
||
}
|
||
const headers = details.requestHeaders || [];
|
||
const setHeader = (name, value) => {
|
||
const existing = headers.find(h => h.name.toLowerCase() === name.toLowerCase());
|
||
existing ? existing.value = value : headers.push({ name, value });
|
||
};
|
||
setHeader("Origin", "https://www.youtube.com");
|
||
setHeader("Referer", "https://www.youtube.com/");
|
||
return { requestHeaders: headers };
|
||
}, { urls: ["*://www.youtube.com/*"] }, ["blocking","requestHeaders"]);
|
||
```
|
||
|
||
> **Para LLMs:** este listener sólo aplica a Firefox MV2 / WebExtensions, donde `declarativeNetRequest` no soporta `modifyHeaders` de la misma forma. **No se ejecuta en Chrome** (donde ya tenemos DNR 9002). En Safari se ignora silenciosamente (`catch` lo traga).
|
||
|
||
### 4.3 `enableYouTubeEmbedRule` (DNR id `9001`) — caso especial, no transcripción
|
||
|
||
No participa en la extracción de transcripción, pero la documentamos para que el lector no se confunda: cuando la popup muestra el `<iframe src="https://www.youtube.com/embed/…">` en modo *Reader*, background fuerza `Referer: https://obsidian.md/` para que el embed no se rompa en vídeos con restricción por referer.
|
||
|
||
---
|
||
|
||
## 5 · `fetchProxy` y `nativeFetch` — por qué existen (y por qué YouTube NO los usa)
|
||
|
||
En `background.js`:
|
||
|
||
```js
|
||
browser_polyfill.runtime.onMessage.addListener(request => {
|
||
if (request.action !== "fetchProxy") return;
|
||
return fetch(request.url, request.options)
|
||
.then(async resp => {
|
||
const text = await resp.text();
|
||
const looksLikeHTML = !resp.ok && (text.includes("Sorry") || text.includes("<html"));
|
||
if (!looksLikeHTML) return { ok: resp.ok, status: resp.status, text, finalUrl: resp.url };
|
||
return browser_polyfill.runtime.sendNativeMessage ? nativeFetch(request.url, request.options) : { ok:false, status:0, error:"CORS_PERMISSION_NEEDED" };
|
||
})
|
||
.catch(() => browser_polyfill.runtime.sendNativeMessage ? nativeFetch(request.url, request.options) : { ok:false, error:"CORS_PERMISSION_NEEDED" });
|
||
});
|
||
```
|
||
|
||
`nativeFetch` usa `runtime.sendNativeMessage("application.id", { type:"fetchRequest", url, method, headers, body })` que solo está disponible en Safari (App‑bound messaging) — sirve para que la app nativa de Mac de Safari haga la petición y devuelva el cuerpo.
|
||
|
||
> **Implicación para YouTube:** la popup **nunca** enruta sus llamadas a YouTube por `fetchProxy` ni por `nativeFetch`. Las llamadas van por `globalThis.fetch` directo, protegidas por la regla DNR 9002.
|
||
|
||
`fetchProxy` se usa en el extractor de **Bilibili** (`BilibiliExtractor`):
|
||
- Llama a `https://api.bilibili.com/x/player/wbi/v2?bvid=…&cid=…` desde la popup.
|
||
- Bilibili suele devolver CORS abierto, así que normalmente no hace falta el proxy. El proxy queda como fallback de seguridad.
|
||
|
||
---
|
||
|
||
## 6 · Estructura del output (qué se mete en la nota Markdown)
|
||
|
||
`YoutubeExtractor.buildResult(transcript)` produce:
|
||
|
||
```js
|
||
{
|
||
content: ` <iframe … src="https://www.youtube.com/embed/{id}" …></iframe><p>{descripción}</p>{transcript.html}`,
|
||
contentHtml: idem,
|
||
extractedContent: { videoId, author },
|
||
variables: {
|
||
title: e.name || "", // videoDetails.title
|
||
author: r, // canal
|
||
site: "YouTube",
|
||
image: Array.isArray(e.thumbnailUrl) ? e.thumbnailUrl[0] : "",
|
||
published: e.uploadDate, // microformat.publishDate o uploadDate
|
||
description: n.slice(0, 200).trim(),
|
||
transcript: transcript.text, // sólo si hay
|
||
language: transcript.languageCode // "en", "es", "es-419", ...
|
||
}
|
||
}
|
||
```
|
||
|
||
`transcript.text` es texto plano con formato Markdown:
|
||
|
||
```
|
||
**00:00** · Primera frase hablada
|
||
|
||
**00:04** · Segunda frase hablada
|
||
```
|
||
|
||
`transcript.html` es:
|
||
|
||
```html
|
||
<div class="youtube transcript">
|
||
<h2>Transcript</h2>
|
||
<p class="transcript-segment"><strong><span class="timestamp" data-timestamp="0">00:00</span></strong> · Primera frase hablada</p>
|
||
…
|
||
</div>
|
||
```
|
||
|
||
Los `transcript-segment` con `data-timestamp` permiten que el modo *Reader* haga **highlight de la línea activa mientras reproduce** (`readerHighlightActiveLine`, `readerPinPlayer`, `readerAutoScroll` — ver `_locales/*/messages.json`).
|
||
|
||
---
|
||
|
||
## 7 · Manejo de errores y degradación
|
||
|
||
| Escenario | Comportamiento observado |
|
||
|---|---|
|
||
| Vídeo sin subtítulos manuales ni auto‑generados | `getCaptionTracks([])` ⇒ `pickCaptionTrack(undefined)` ⇒ `null` ⇒ `buildResult` se llama con `transcript = undefined` ⇒ `variables.transcript` queda ausente. El iframe y los metadatos sí se guardan. |
|
||
| Vídeo con subtítulos sólo auto (`kind:"asr"`) | `pickCaptionTrack` la prefiere si no hay otra o si la opción `language` coincide; en otro caso la salta. |
|
||
| `fetchPlayerData` falla en los 3 clientes y no hay JSON embebido | `transcript` queda `undefined`. La popup sigue mostrando la nota con metadatos. |
|
||
| Red lenta / timeout 4 s | `AbortSignal.timeout(4000)` corta la petición. Se prueba el siguiente cliente. |
|
||
| CORS aún bloqueado pese a DNR 9002 | En Chrome MV3 no hay fallback automático desde background (no usa `fetchProxy` para YouTube). El error queda silenciado dentro del `try { … } catch {}` y la nota se guarda sin transcripción. |
|
||
| Página no es `youtube.com` (p.ej. embed de otro dominio) | `canExtractAsync()` devuelve `false`; Defuddle cae a su extractor genérico (`BbcodeDataExtractor` según `ExtractorRegistry.mappings[last]`). |
|
||
|
||
---
|
||
|
||
## 8 · Datos estáticos y constantes que un LLM debe conocer
|
||
|
||
### 8.1 Versiones de cliente (claves de la firma)
|
||
|
||
| Variable | Valor | Notas |
|
||
|---|---|---|
|
||
| `ANDROID_CLIENT_VERSION` | `20.10.38` | Cliente ANDROID. |
|
||
| `IOS_CLIENT_VERSION` | `20.10.3` | Cliente IOS. |
|
||
| `WEB_CLIENT_VERSION` | `2.20240101.00.00` | Cliente WEB clásico. |
|
||
| `ANDROID_USER_AGENT` | `com.google.android.youtube/20.10.38 (Linux; U; Android 14)` | Solo se envía en el 2º intento. |
|
||
| `PLAYER_ENDPOINT` | `https://www.youtube.com/youtubei/v1/player?prettyPrint=false` | — |
|
||
| `NEXT_ENDPOINT` | `https://www.youtube.com/youtubei/v1/next?prettyPrint=false` | Solo `fetchChapters`. |
|
||
| `TIMEOUT_MS` | `4000` | `AbortSignal.timeout`. |
|
||
| `LANG_HEADER` | `Accept-Language` (opcional) | Se añade sólo si `options.language` está definido. |
|
||
|
||
### 8.2 Reglas DNR declaradas por background
|
||
|
||
| id | Nombre interno | Trigger | Acción | Uso |
|
||
|---|---|---|---|---|
|
||
| `9001` | `enableYouTubeEmbedRule` | `urlFilter:"||youtube.com/embed/"`, `resourceTypes:["sub_frame"]`, `tabIds:[<sender tab>]` | `set Referer: https://obsidian.md/` | Solo embeds (no transcripción). |
|
||
| `9002` | `enableYouTubeInnertubeRule` | `urlFilter:"||youtube.com/youtubei/"`, `resourceTypes:["xmlhttprequest"]`, `initiatorDomains:[chrome.runtime.id]` | `set Origin: https://www.youtube.com`, `set Referer: https://www.youtube.com/` | **Clave para que funcione la extracción.** |
|
||
|
||
### 8.3 Selectores DOM relevantes
|
||
|
||
| Uso | Selector |
|
||
|---|---|
|
||
| Panel de transcripción (desktop) | `ytd-engagement-panel-section-list-renderer[target-id="engagement-panel-searchable-transcript"] #segments-container` |
|
||
| Botón "Mostrar transcripción" | `ytd-video-description-transcript-section-renderer button` |
|
||
| Idioma seleccionado en panel | `ytd-engagement-panel-section-list-renderer[target-id="engagement-panel-searchable-transcript"] #footer yt-sort-filter-sub-menu-renderer yt-dropdown-menu button` |
|
||
| Panel mobile | `ytm-macro-markers-list-renderer .ytm-macro-markers-list-container` |
|
||
| Botón "Show more" mobile | `button[aria-label="Show more"]` |
|
||
| Botón "View all" mobile | `button[aria-label="View all"]` |
|
||
| Segmento desktop | `ytd-transcript-segment-renderer` (timestamp `.segment-timestamp`, texto `.segment-text`) |
|
||
| Segmento mobile | `transcript-segment-view-model` (timestamp `.ytwTranscriptSegmentViewModelTimestamp`, texto `span.yt-core-attributed-string`) |
|
||
| Metadatos (LD+JSON) | `script[type="application/ld+json"]` buscando `VideoObject` |
|
||
| OpenGraph | `meta[property="og:title|og:description|og:image|og:url"]` |
|
||
| Nombre de canal (DOM) | `[itemprop="name"]` / `link[itemprop="name"]` / `a, span` |
|
||
| JSON embebido | `<script>` con `ytInitialPlayerResponse` o `ytInitialData` |
|
||
|
||
### 8.4 Mensajes i18n ligados a la transcripción
|
||
|
||
`_locales/*/messages.json` contiene (en cada idioma) entradas como:
|
||
|
||
- `readerTranscripts` → "Transcripts" / "Transcripciones" / "Transcriptions" / …
|
||
- `readerHighlightActiveLine` / `…Description` → toggle de la línea activa
|
||
- `readerPinPlayer` / `…Description` → fija el reproductor
|
||
- `readerAutoScroll` / `…Description` → auto‑scroll durante reproducción
|
||
- `readerThemeSection` → tema de la transcripción en el Reader
|
||
|
||
(Solo configuran el render, no el proceso de extracción.)
|
||
|
||
---
|
||
|
||
## 9 · Diagrama textual del flujo de red
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ popup.html / side-panel.html (chrome-extension://) │
|
||
│ ┌────────────────┐ │
|
||
│ │ popup.js │ │
|
||
│ │ Defuddle + │ │
|
||
│ │ YoutubeExtractor │
|
||
│ └───┬────────────┘ │
|
||
│ │ globalThis.fetch (XHR) │
|
||
│ ▼ │
|
||
│ https://www.youtube.com/youtubei/v1/player?… │
|
||
│ Body: { context: <IOS|ANDROID|WEB>, videoId } │
|
||
└──────────────────────────────────────────────────────┘
|
||
│ (DNR rule 9002)
|
||
│ set Origin: https://www.youtube.com
|
||
│ set Referer: https://www.youtube.com/
|
||
▼
|
||
YouTube InnerTube API
|
||
│ JSON con captionTracks[*].baseUrl
|
||
▼
|
||
https://www.youtube.com/api/timedtext?…&fmt=…&v=…&lang=… (track.baseUrl)
|
||
│ Headers: User-Agent: Mozilla/5.0
|
||
│ Accept-Language: <opción del usuario>
|
||
▼
|
||
XML de subtítulos
|
||
│ parseTranscriptXml()
|
||
▼
|
||
{ html, text, languageCode }
|
||
│
|
||
▼
|
||
variables.transcript + variables.language
|
||
⇒ se inyecta en la nota Markdown
|
||
```
|
||
|
||
Paralelo: `fetchChapters` → `https://www.youtube.com/youtubei/v1/next?…` con `client: WEB` ⇒ `playerOverlays…markersMap` ⇒ capítulos embebidos como `## H2` dentro del HTML de la transcripción.
|
||
|
||
---
|
||
|
||
## 10 · Riesgos y consideraciones para mantenimiento
|
||
|
||
1. **Versiones hard‑coded de cliente (`20.10.38`, `20.10.3`, `2.20240101.00.00`)**: YouTube rota las firmas mensualmente. Si la transcripción deja de funcionar, lo primero a actualizar son estas tres constantes en `popup.js` y `reader-page.js` (buscar `clientVersion` y `20.10.38`).
|
||
2. **DNR `9002` solo en `xmlhttprequest`**: si YouTube migra a `fetch` puro o cambia el `resourceType`, la regla deja de aplicar. Verificar `chrome.declarativeNetRequest.getEnabledRulesets()` en la consola de la extensión.
|
||
3. **`fetchProxy` NO se usa para YouTube**: no intentes enrutar por ahí; el flujo correcto es `globalThis.fetch` + DNR.
|
||
4. **El content script no extrae transcripción**: si la popup falla, no hay fallback desde `content.js`. Mejorar la extracción implica tocar `popup.js` y `reader-page.js` (que son el mismo bundle).
|
||
5. **Cache `Map<key, transcript>`**: existe en `BilibiliExtractor.transcriptCache` (LRU con cap 300). `YoutubeExtractor` **no** cachea transcripciones; cada `extract` rehace la red.
|
||
6. **Permisos**: el manifest pide `<all_urls>` y `declarativeNetRequest`. Si se reduce a un `optional_host_permissions` específico de YouTube, la popup seguirá funcionando porque `youtubei` está cubierto por `host_permissions`, pero el `webRequest` listener de Firefox puede dejar de aplicar.
|
||
7. **Time limit de service worker (MV3)**: el SW se duerme tras 30 s. `enableYouTubeInnertubeRule` se registra en `initialize()` al arrancar y se elimina solo si se pide `disableYouTubeInnertubeRule` (que no existe en el código actual). En la práctica, la regla es *session‑scoped* y dura lo que dure la sesión de Chrome.
|
||
8. **`ytInitialPlayerResponse` puede no estar presente** en páginas con cookie consent previo o si el usuario está en `consent.youtube.com`. La cascada ANDROID/IOS/WEB lo cubre.
|
||
|
||
---
|
||
|
||
## 11 · Resumen para indexar/embeddings
|
||
|
||
> Texto generado para ser embeddings‑friendly. 7 frases autocontenidas.
|
||
|
||
1. La extensión **Obsidian Web Clipper 1.7.1** extrae la transcripción de YouTube desde la **popup** (contexto de la extensión, `chrome-extension://`), nunca desde el content script.
|
||
2. La clase **`YoutubeExtractor`** (minificada en `popup.js` y duplicada en `reader-page.js`, originalmente de Defuddle) ofrece una cascada de tres rutas: (a) parseo del JSON embebido `ytInitialPlayerResponse`, (b) scraping del panel de transcripción DOM con selectores `ytd-transcript-segment-renderer` / `transcript-segment-view-model`, (c) peticiones a la API privada **`youtubei/v1/player`** con contextos de cliente ANDROID / IOS / WEB.
|
||
3. El bypass de CORS / firma se hace con una regla **`declarativeNetRequest` id 9002** que fuerza `Origin: https://www.youtube.com` y `Referer: https://www.youtube.com/` para todas las XHR a `||youtube.com/youtubei/` iniciadas por la propia extensión; Firefox usa `webRequest.onBeforeSendHeaders` en su lugar.
|
||
4. La pista de subtítulos descargada (`track.baseUrl` con sufijo `fmt=`) es XML y se parsea con dos regex: `<p t="N">…<s>…</s>…</p>` (formato moderno) y `<text start="N">…</text>` (formato legacy), produciendo HTML con clase `transcript-segment` y texto plano con timestamps `HH:MM:SS`.
|
||
5. Los **capítulos** se extraen de `ytInitialData` o, en su defecto, de `youtubei/v1/next` con cliente WEB, parseando `playerOverlays.playerOverlayRenderer.decoratedPlayerBarRenderer.multiMarkersPlayerBarRenderer.markersMap`.
|
||
6. La popup usa `globalThis.fetch` directo (sin proxy) para YouTube; el `fetchProxy`/`nativeFetch` de `background.js` solo se utiliza como fallback CORS para Bilibili y otros hosts, no para YouTube.
|
||
7. El resultado (`{transcript.text, language}`) se inyecta en la nota Markdown final bajo la variable `transcript` / `language`; la nota incluye también un `<iframe src="https://www.youtube.com/embed/{id}">` y metadatos (`title`, `author`, `image`, `published`, `description`).
|
||
|
||
---
|
||
|
||
*Fin del informe.*
|