1. Recommended workflow

1. Sign in and save your YouTube API Key. The key is used only to request YouTube data for your own mining operations.
2. Choose a Mining Depth™. Quick Scan™ reads up to 100 comments, Deep Mine™ up to 500, and Full Spectrum™ up to 1,000.
3. Choose the Sampling Method. Smart Sampling™ is recommended. It combines relevant/top comments with recent conversation and removes duplicates. Sequential follows the relevance order returned by YouTube.
4. Mine a URL or an existing channel. For a single analysis, select a video and use Mine Selected Video. This updates or completes comment mining for one video only, and can be used again when you need more coverage.
5. Read the result in context. Start with Mining Coverage and Advisor Confidence, then review the KPIs, timeline, detected moments and the comments supporting them.
6. Generate the Advisor or PDF report. The Advisor interprets the already-mined evidence. The Full Report reuses that stored analysis and does not make another AI request.

Video tutorials: ▶ How to get your YouTube API Key · ▶ How to get your Gemini API Key

Background mining: all channel mining operations run as background jobs. Once started, a full-screen overlay appears showing live progress — videos processed, comments analyzed and moments found. Do not close or refresh the tab during mining. Deep Mine™ and Full Spectrum™ may take several minutes per batch.

Three mining buttons: 🆕 New + Mine — fetches the most recent N videos not yet in your catalog (select 20, 25 or 30 with the "Obtain N new videos" control) and then mines the best batch of those (Quick Scan™ mines 10, Deep Mine™ mines 5, Full Spectrum™ mines 3). If the catalog is already up to date you will see a notification instead of the overlay. ⏳ Mine Pending — mines the next batch of catalog videos that still have no comment analysis; run it again until none remain. 🔄 Update Mined — re-mines already-analyzed videos that are 7+ days old so their moment scores reflect recent comment activity. Use the Mining Settings Bar (visible after login) to choose depth, sampling and how many new videos to fetch before clicking any button.

Usage counters: YouTube shows both API requests issued by YTMoments and quota units consumed under your personal key during the current UTC day. The safe key fingerprint identifies which key is being measured. Google Cloud can differ if you inspect another key/project or the same key is used outside YTMoments. Advisor separates completed analyses charged to the plan from technical Gemini requests and tokens. A retry may add an API request without charging another Advisor analysis.

API key strategy: Admin has private central system keys for YouTube and Gemini, but those keys are not shared with SaaS customers. Customer priority is: personal user key first, workspace primary key second. If neither exists or its Google quota is exhausted, the customer must configure or rotate their own key. This BYOA model keeps each agency/client responsible for its own free daily Google capacity.

SaaS workspaces: every customer or agency has one private workspace. All members of that workspace share its channels, videos, YouTube key, plan, courtesy period, extra Advisor credits and usage counters. Individual user identities remain visible in the audit trail, but creating additional members does not create additional quota.

Share Room access: every authorized recipient receives an individual six-digit PIN. Telegram delivers only the PIN linked to that email invitation, and its delivery token works once. Revoking or blocking one recipient does not expose or change another recipient's access.

API capacity reference

• Mining does not consume Gemini. Channel and video mining use the YouTube Data API only; Gemini is called only when generating a new Advisor analysis.
• Typical Advisor request: approximately 700–1,200 input tokens and 350–700 output tokens. Actual usage depends on the mined evidence and report length.
• YouTube channel estimate (🆕 New + Mine): Quick Scan™ (10 videos) usually consumes about 23–53 units, Deep Mine™ (5 videos) 23–53, Full Spectrum™ (3 videos) 13–33. Pagination of new videos and Smart Sampling can change these values.
• Gemini free capacity: Google applies requests-per-minute, tokens-per-minute and requests-per-day limits per Google Cloud project. The active limit shown in Google AI Studio is authoritative; YTMoments also applies its configured safety ceiling.
• Gemini key priority: Video Advisor, Channel Advisor and Brand Advisor use the user's Gemini key when present; otherwise they use the workspace key. Central/Admin Gemini keys are exclusive to Admin and are not used as fallback for SaaS customers. Mining itself never calls Gemini.

2. Mining Depth™ and sampling

Important: "up to" means the final number may be lower when YouTube returns fewer available comments, comments are disabled, pages overlap, or the API does not expose the complete public total.

3. Proprietary YTMoments metrics

Practical examples: Focus Peak™ 82/100 means one moment concentrated strong audience evidence; Trace Map™ 18% means many analyzed comments referenced exact seconds; Clip Yield™ 3.2 / 10m means the channel is producing several reusable clip opportunities per 10 minutes of content.

Agency transparency: formulas and heuristics

Methods note: YTMoments complements YouTube Studio from a different angle: engagement, emotion and subscriber language inside public comments. Agencies and creators should keep using YouTube Studio for retention, views, watch time and traffic sources, then use YTMoments to understand what the audience felt, repeated, timestamped, debated or turned into a sponsor signal.

4. Advisor Confidence

• Low: fewer than 50 comments, or no detected moments.
• Medium: there is usable evidence, but the sample is limited; this also applies when at least 500 comments represent less than 1% coverage.
• High: at least 500 comments and at least 3 detected moments.

The confidence level evaluates the evidence available to the Advisor. It does not certify that the sample represents every viewer, and it does not measure whether a recommendation will succeed.

5. Advisor skills and behavior

The Advisors behave like an agency strategy team reading mined evidence: they separate editorial, community and commercial signals, turn them into actions, and lower certainty when the data is thin.

6. How to read each area

• Video DNA™ overlay and timeline: marker height represents moment strength, while color represents the dominant audience signal: green Humor, red Controversy, blue Surprise, purple Emotion and yellow Brand. Gray means there is not enough evidence for one of those families. Click a marker to move the player to that second.
• YTMoments Share Rooms™: create private rooms for three scopes: video reports, channel reports and Brand Search™ reports. Rooms can last 24 hours or 7 days, expose only the sections selected by the owner, authorize recipients by email and protect each recipient with an individual PIN. The owner can invite more participants later, revoke a participant without deleting evidence, close/reopen the room and export the work log or final agreements.
• Brand & Term Search™: detects recurring brand candidates across your private mined workspace. It reports mentions, accumulated likes, videos, timestamps, highlighted comments and detected audience reactions. Brand Advisor creates a brand-specific interpretation and caches it per workspace, term and language; when new evidence appears, the analysis can be refreshed. Data from the public demo and other users is excluded.
• YTMoments Share Rooms™: create a private review room for 24 hours or 7 days. Choose the visible sections, authorize one or more recipient emails and protect access with a required six-digit PIN. YTMoments emails only the link; share the PIN separately. Use the main Share button for the report or the link icon on a detected moment for an editor-ready room. Recent rooms show status, expiration, views and recipients, and may be revoked immediately.
• Brand & Term Search™: detects recurring brand candidates across your private mined workspace. It reports mentions, accumulated likes, videos, timestamps, highlighted comments and detected audience reactions. Data from the public demo and other users is excluded.
• AI Advisor: summarizes the stored metrics, evidence and coverage. It must lower the strength of its conclusions when the evidence is weak. When reply threads contain polarizing debates (stereotypes, gender, regionalism), the Advisor classifies them as either an Editorial Opportunity (reframe the controversy into constructive content) or a Brand Safety Flag (risk that sponsors or partners may need to evaluate).
• One-Pager: concise executive summary. Full Report: two pages containing the key Advisor findings, principal moments and relevant comments from the same stored analysis.
• Audience Diagnostic™ in PDF Channel Report: the channel PDF report includes a dedicated page listing every mined video with its Focus Peak™ color-coded (green ≥ 70, amber 40–69, dark < 40), comments, Clips, Vibe Power™ and Core Trigger™. This gives a complete audit trail of the evidence base behind the Advisor conclusions.

7. Channel Hub Intelligence™

The Channel Hub provides channel-level intelligence across all mined videos in your workspace.

• Active channel chip: a green banner at the top of the Hub always shows the channel being analyzed, even when scrolling through long results.
• Views vs Focus Peak™ scatter plot: each circle represents one video. The horizontal axis (log scale) shows YouTube view count; the vertical axis shows Focus Peak™ (0–100). Circle size reflects the number of comments analyzed. The dashed yellow line at Focus Peak 25 is the evidence threshold — videos above it have meaningful mined moments. Quadrant labels identify "High views, low evidence" (many views but no strong hook signal) vs "High views + evidence" (well-performing with confirmed audience moments).
• Audience Diagnostic™ table: all mined videos sorted by views, with columns for coverage %, Focus Peak™, hook second and hook strength. Each row is classified as: Good (has a moment above the evidence threshold), Warn (insufficient comments or coverage — mine deeper), or Passive (many views but no detected hook — genuine passive consumption). Use this table to identify which videos need more mining vs those that simply have passive audiences.

8. Sessions and access

• One active session per account: each user account allows only one active session at a time. Signing in on a second device automatically invalidates the previous session; the other device will be prompted to sign in again on its next action.
• Admin accounts are exempt from this restriction and may maintain simultaneous sessions on multiple devices.
• Workspace sessions: multiple users in the same workspace each hold their own independent session. Only concurrent sessions for the same user account are restricted.
• Admin: change user password. In the Users section of the Admin panel, each user row includes a "Change password" button. The new password must be at least 10 characters. Changing it invalidates the user's active session immediately; the user must sign in again with the new password.

9. Interpretation rules

A high Score 100 means stronger conversation around a timestamp, not necessarily higher audience retention. Low coverage does not make the analysis useless, but conclusions should be treated as directional. Always combine YTMoments with YouTube Studio retention, traffic sources and business context before making major editorial or advertising decisions.

1. Flujo recomendado

1. Inicia sesión y guarda tu API Key de YouTube. Se utiliza únicamente para solicitar a YouTube los datos de tus operaciones de minería.
2. Selecciona una Profundidad de Minería™. Quick Scan™ procesa hasta 100 comentarios, Deep Mine™ hasta 500 y Full Spectrum™ hasta 1,000.
3. Selecciona el Método de Muestreo. Smart Sampling™ es el recomendado. Combina comentarios relevantes con conversación reciente y elimina duplicados. Sequential sigue el orden de relevancia entregado por YouTube.
4. Mina una URL o un canal existente. Para un análisis individual, selecciona el video y usa Minar Video Seleccionado. Esto actualiza o completa la minería de comentarios de un solo video y puede usarse de nuevo cuando necesitas más cobertura.
5. Lee el resultado con contexto. Comienza por Cobertura de Minería y Confianza del Advisor; después revisa KPIs, timeline, momentos detectados y los comentarios que los respaldan.
6. Genera el Advisor o el reporte PDF. El Advisor interpreta la evidencia ya minada. El Reporte Completo reutiliza ese análisis guardado y no realiza otra consulta de IA.

Video tutoriales: ▶ Cómo obtener tu API Key de YouTube · ▶ Cómo obtener tu API Key de Gemini

Minería en background: todas las operaciones de minería de canales corren como tareas en segundo plano. Al iniciar, aparece un overlay de pantalla completa con progreso en vivo: videos procesados, comentarios analizados y momentos encontrados. No cierres ni recargues la pestaña durante la minería. Deep Mine™ y Full Spectrum™ pueden tomar varios minutos por lote.

Tres botones de minería: 🆕 Nuevos + Minar — obtiene los N videos más recientes que aún no están en el catálogo (elige 20, 25 ó 30 con el control "Obtener N videos nuevos") y mina el mejor lote de esos (Quick Scan™ mina 10, Deep Mine™ mina 5, Full Spectrum™ mina 3). Si el catálogo ya está al día recibirás una notificación en vez del overlay. ⏳ Minar Pendientes — mina el siguiente lote de videos del catálogo que todavía no tienen análisis; ejecútalo de nuevo hasta que no queden pendientes. 🔄 Actualizar Minados — re-mina videos ya analizados con 7+ días de antigüedad para que sus momentos reflejen la actividad reciente de comentarios. Usa la Barra de Configuración de Minería (visible tras iniciar sesión) para elegir profundidad, muestreo y cuántos videos nuevos obtener antes de pulsar cualquier botón.

Contadores de consumo: YouTube muestra las solicitudes realizadas por YTMoments y las unidades de cuota consumidas bajo tu clave personal durante el día UTC actual. La huella segura permite identificar qué clave se está midiendo. Google Cloud puede diferir si consultas otra clave/proyecto o si la misma clave se usa fuera de YTMoments. El Advisor separa los análisis completados cobrados al plan de las solicitudes técnicas y tokens de Gemini. Un reintento puede sumar una solicitud API sin cobrar otro análisis Advisor.

Estrategia de API Keys: Admin tiene llaves centrales privadas para YouTube y Gemini, pero esas llaves no se comparten con clientes SaaS. La prioridad del cliente es: key personal del usuario primero y key primaria del workspace segundo. Si ninguna existe o se agota su cuota de Google, el cliente debe configurar o rotar su propia key. Este modelo BYOA mantiene la capacidad gratuita diaria bajo responsabilidad de cada agencia/cliente.

Workspaces SaaS: cada cliente o agencia tiene un workspace privado. Todos sus miembros comparten canales, videos, clave de YouTube, plan, periodo de cortesía, créditos extra del Advisor y contadores de consumo. La identidad individual se conserva para auditoría, pero crear más miembros no genera cuotas adicionales.

Acceso a Share Rooms: cada destinatario autorizado recibe un PIN individual de seis dígitos. Telegram entrega únicamente el PIN vinculado a esa invitación por correo y su token funciona una sola vez. Revocar o bloquear a un destinatario no expone ni modifica el acceso de los demás.

Referencia de capacidad de las APIs

• El minado no consume Gemini. Minar canales y videos utiliza únicamente YouTube Data API; Gemini se consulta solamente al generar un nuevo análisis Advisor.
• Consulta Advisor típica: aproximadamente 700–1,200 tokens de entrada y 350–700 de salida. El consumo real depende de la evidencia minada y la extensión del reporte.
• Estimación por canal (🆕 Nuevos + Minar): Quick Scan™ (10 videos) suele consumir 23–53 unidades de YouTube, Deep Mine™ (5 videos) 23–53, Full Spectrum™ (3 videos) 13–33. La paginación de videos nuevos y Smart Sampling pueden modificar estas cifras.
• Capacidad gratuita de Gemini: Google aplica límites de solicitudes por minuto, tokens por minuto y solicitudes diarias por proyecto de Google Cloud. El límite activo mostrado en Google AI Studio es el definitivo; YTMoments además aplica su propio techo preventivo configurado.
• Prioridad de Gemini: Video Advisor, Channel Advisor y Brand Advisor usan la key Gemini del usuario si existe; si no, usan la key del workspace. Las llaves centrales/Admin de Gemini son exclusivas de Admin y no se usan como respaldo para clientes SaaS. El minado nunca consume Gemini.

2. Profundidad de Minería™ y muestreo

Importante: "hasta" significa que la cifra final puede ser menor si YouTube devuelve menos comentarios disponibles, los comentarios están desactivados, las páginas se traslapan o la API no expone todo el total público.

3. Métricas propias de YTMoments

Ejemplos prácticos: Focus Peak™ 82/100 significa que un momento concentró evidencia fuerte de audiencia; Trace Map™ 18% significa que muchos comentarios analizados mencionaron segundos exactos; Clip Yield™ 3.2 / 10m significa que el canal produce varias oportunidades reutilizables de clip por cada 10 minutos de contenido.

Transparencia para agencias: fórmulas y heurísticas

Nota metodológica: YTMoments complementa YouTube Studio desde otro ángulo: enganche, emoción y lenguaje de suscriptores dentro de los comentarios públicos. Las agencias y creadores deben seguir usando YouTube Studio para retención, vistas, tiempo de reproducción y fuentes de tráfico, y usar YTMoments para entender qué sintió la audiencia, qué repitió, qué marcó con timestamps, qué debatió o qué convirtió en señal para patrocinio.

4. Confianza del Advisor

• Baja: menos de 50 comentarios o ningún momento detectado.
• Media: existe evidencia útil, pero la muestra es limitada; también aplica cuando 500 o más comentarios representan menos de 1% de cobertura.
• Alta: al menos 500 comentarios y 3 o más momentos detectados.

La confianza evalúa la evidencia disponible para el Advisor. No certifica que la muestra represente a todos los espectadores ni mide si una recomendación tendrá éxito.

5. Habilidades y comportamiento de los Advisor

Los Advisors se comportan como un equipo estratégico de agencia leyendo evidencia minada: separan señales editoriales, de comunidad y comerciales, las convierten en acciones y bajan la certeza cuando los datos son limitados.

6. Cómo leer cada área

• Video DNA™ en la gráfica y timeline: la altura representa la fuerza del momento y el color su señal dominante: verde Humor, rojo Polémica, azul Sorpresa, morado Emoción y amarillo Marca. El gris indica que todavía no hay evidencia suficiente para clasificarlo en esas familias. Haz clic en un marcador para mover el reproductor a ese segundo.
• Narrative Signal Flow™: mapea la intensidad de interacción observada durante el video utilizando timestamps, menciones, likes y respuestas minadas. Verde indica activación, amarillo observación, rojo una zona fría de interacción y gris evidencia insuficiente. No mide retención ni demuestra abandono de espectadores.
• Momentos y comentarios con timestamp: el lado izquierdo es un índice analítico compacto con score, menciones y engagement. Selecciona un momento para filtrar a la derecha únicamente los comentarios que respaldan su ventana de tiempo; usa Ver todos para recuperar la evidencia completa.
• YTMoments Share Rooms™: crea salas privadas para tres alcances: reportes de video, reportes de canal y reportes de Brand Search™. Pueden vivir 24 horas o 7 días, mostrar solo las secciones elegidas por el propietario, autorizar destinatarios por correo y proteger cada acceso con PIN individual. El propietario puede invitar más participantes después, revocar a un participante sin borrar evidencia, cerrar/reabrir la sala y exportar la bitácora o acuerdos finales.
• Brand & Term Search™: detecta candidatos recurrentes de marca en todo tu workspace privado minado. Presenta menciones, likes acumulados, videos, timestamps, comentarios destacados y reacciones detectadas. Brand Advisor genera una interpretación específica por marca y la cachea por workspace, término e idioma; cuando aparece nueva evidencia, el análisis puede actualizarse. Excluye datos demo públicos y datos de otros usuarios.
• Advisor IA: resume métricas, evidencia y cobertura almacenadas. Debe moderar sus conclusiones cuando la evidencia es débil. Cuando los hilos de respuesta contienen debates polarizantes (estereotipos, género, regionalismos), el Advisor los clasifica como Oportunidad Editorial (reconvertir la polémica en contenido constructivo) o Alerta de Brand Safety (riesgo que patrocinadores o aliados pueden necesitar evaluar).
• Resumen: reporte ejecutivo breve. Reporte Completo: dos páginas con hallazgos principales del Advisor, momentos clave y comentarios relevantes del mismo análisis guardado.
• Audience Diagnostic™ en el Reporte PDF de Canal: el PDF del canal incluye una página dedicada con todos los videos minados, Focus Peak™ en color (verde ≥ 70, ámbar 40–69, oscuro < 40), comentarios, Clips, Vibe Power™ y Core Trigger™. Proporciona la auditoría completa de evidencia detrás de las conclusiones del Advisor.

7. Channel Hub Intelligence™

El Channel Hub proporciona inteligencia a nivel de canal sobre todos los videos minados en tu workspace.

• Chip de canal activo: un banner verde en la parte superior del Hub muestra siempre el canal que se está analizando, incluso al hacer scroll por resultados largos.
• Scatter plot Vistas vs Focus Peak™: cada círculo representa un video. El eje horizontal (escala logarítmica) muestra las vistas de YouTube; el eje vertical muestra el Focus Peak™ (0–100). El tamaño del círculo refleja los comentarios analizados. La línea amarilla punteada en Focus Peak 25 es el umbral de evidencia — los videos por encima tienen momentos de audiencia significativos. Las etiquetas de cuadrante identifican "Muchas vistas, poca evidencia" vs "Muchas vistas + evidencia confirmada".
• Tabla Audience Diagnostic™: todos los videos minados ordenados por vistas, con columnas de cobertura %, Focus Peak™, segundo del hook y fuerza del hook. Cada fila se clasifica como: Bueno (tiene momento sobre el umbral), Alerta (comentarios o cobertura insuficiente — mina más profundo), o Pasivo (muchas vistas pero sin hook detectado — consumo genuinamente pasivo). Usa esta tabla para saber qué videos necesitan más minería versus cuáles simplemente tienen audiencia pasiva.

8. Sesiones y acceso

• Una sesión activa por cuenta: cada cuenta de usuario permite solo una sesión activa a la vez. Al iniciar sesión en un segundo dispositivo, la sesión anterior queda invalidada automáticamente; el otro dispositivo recibirá un aviso al realizar su siguiente acción.
• Cuentas Admin están exentas de esta restricción y pueden mantener sesiones simultáneas en múltiples dispositivos.
• Sesiones de workspace: los distintos usuarios de un mismo workspace tienen cada uno su propia sesión independiente. Solo las sesiones concurrentes del mismo usuario están restringidas.
• Admin: cambio de contraseña de usuario. En la sección Usuarios del panel Admin, cada fila incluye el botón "Cambiar contraseña". La nueva contraseña debe tener mínimo 10 caracteres. El cambio invalida la sesión activa del usuario de inmediato; el usuario debe iniciar sesión de nuevo con la nueva contraseña.

9. Reglas de interpretación

Un Score 100 alto significa conversación más fuerte alrededor de un timestamp, no necesariamente mayor retención de audiencia. Una cobertura baja no vuelve inútil el análisis, pero sus conclusiones deben considerarse direccionales. Combina siempre YTMoments con retención, fuentes de tráfico y contexto de negocio de YouTube Studio antes de tomar decisiones editoriales o publicitarias importantes.