Presenter — presentar un documento (o un tema) en una reunión
Un bot de IA se une a una reunión y presenta: por defecto, la presentación se muestra en grande en el escenario principal de la reunión como una pantalla compartida, narrada con la voz del bot y avanzando automáticamente, con la cara del bot en un pequeño recuadro de cámara. (Pasa --avatar-mode — o si el usuario dice "únete en modo avatar" — para mostrar la presentación en el recuadro de la cámara, el aspecto original de una sola baldosa). Sin control remoto de todas formas.
Modos de visualización: pantalla compartida es el predeterminado (diapositivas legibles en pantalla completa + una cara de presentador); modo avatar (--avatar-mode) pone la presentación solo en el recuadro de la cámara. Todo lo demás — control por voz, el control remoto complementario, la narración, las preguntas y respuestas — funciona de manera idéntica en ambos.
El caso de uso principal: el usuario proporciona un enlace de reunión y un documento — PDF, PowerPoint o Word — y el bot lo presenta. También puedes empezar solo con un tema.
Haz esto en orden (todo el flujo — siempre igual, sin desvíos)
0 · Verificación previa (una vez).
- Clave API — verifica en este orden, y NO preguntes si ya está presente (una configuración, el MISMO archivo que usa AgentCall; este es el orden exacto que usa
load_api_key):- ¿Existe
~/.agentcall/config.jsoncon unapi_key? → listo. - ¿Está definida la variable de entorno
AGENTCALL_API_KEY? → listo. - ¿Ninguna? → pide al usuario su clave (gratis en agentcall.dev/api-keys) y escríbela en
~/.agentcall/config.json(consulta Configuración) — creando ese archivo exactamente como lo haría AgentCall — luego continúa.
- ¿Existe
- Dependencias —
pip install -r requirements.txt(rápido; ruedas de Python puro, sin herramientas del sistema).
1 · Convierte la entrada en una presentación. Tú (el agente) eres siempre el dueño de la narración — nunca dejes que el bot lea la diapositiva de la pantalla. Ejecuta doc_to_deck.py primero, luego mira lo que produjo:
- Un
.pptx/.ppt, o un PDF con forma de diapositiva → muestra las diapositivas reales, pero la narración es tuya:- Si el archivo tiene notas del orador en cada diapositiva (solo
.pptx— las notas de.pptheredadas no se pueden leer; pide un.pptx), se convierten en la narración — has terminado, solo presenta. Notas solo en ALGUNAS diapositivas → la presentación está marcada; redacta las que faltan. - Si no tiene notas, la presentación vuelve marcada como
needs_narrationcon todos losnotesvacíos (y undecks/<name>/source.json). Redacta una línea denoteshablada por diapositiva (leesource.json+ echa un vistazo a las imágenes de las diapositivas) antes de presentar —present.pyse niega a ejecutar una presentación convertida no redactada, así que no hay atajo. Redactar ES presentar.
- Si el archivo tiene notas del orador en cada diapositiva (solo
- Un
.docx/.doc, un PDF estilo informe, o un tema → redacta una presentación: ejecutadoc_to_deck.py --mode generate, leedecks/<name>/source.json(su texto + figuras extraídas) y escribedecks/<name>/deck.json. NO intentes abrir o renderizar el archivo tú mismo (sinpdftoppm, sin herramientas de imagen) —source.jsones tu entrada. Mantén la redacción ajustada: una idea por diapositiva, viñetas cortas, narración natural — no sobrepulir. - El trabajo redactado está protegido, pero solo en la carpeta de presentación PREDETERMINADA. Volver a ejecutar la conversión (o
present.py --deck <mismo documento>) con una fuente sin cambios reutiliza eldeck.jsonredactado endecks/<name>/— instantáneo, nada se vuelve a renderizar, tu narración sobrevive. Solo se reconvierte cuando el documento en sí ha cambiado (entonces vuelve a redactar — la bandera regresa). NO pases--out <una carpeta diferente>para un documento que redactarás y presentarás — una carpeta nueva no tiene presentación que reutilizar, por lo que obtienes un borrador con notas vacías (y la presentación redactada real se vuelve obsoleta).--outes solo para conversiones desechables/de inspección. Redacta, presenta y vuelve a presentar desde eldecks/<name>/deck.jsonpredeterminado. - Detalle completo + esquema de la presentación: secciones A y B a continuación.
Reglas estrictas (cada una ha quemado una sesión real — el código aplica la mayoría, no luches contra ello):
- Nunca envíes un documento sin procesar directamente a
present.pyy te vayas. Convierte → verificaneeds_narration→ redactanotes→ presenta. La salida de rechazo (código 2) es tu señal para redactar, no un error que debas evitar. - Nunca sobrescribas un
deck.jsonredactado reconvirtiendo. Fuente sin cambios → se reutiliza automáticamente; solo elimina la carpeta de la presentación si el usuario quiere explícitamente una conversión nueva. - Nunca inventes una presentación de relleno ni te disculpes en cámara. Si la conversión falla, present.py sale — arregla la entrada (o instala LibreOffice) y relanza. Un bot que nunca se une es mejor que uno que se ve roto.
- Nunca dejes una llamada en ejecución. present.py detiene la facturación en cada ruta de salida por sí mismo — pero si TÚ lo iniciaste, confirma que el proceso realmente salió cuando termina la presentación.
1b · Honra las instrucciones del usuario — sus instrucciones dan forma a la presentación Y a cómo la conduces. Cuando el usuario dice algo más allá de "presenta esto", captúralo y aplícalo. Aterriza en uno de dos lugares:
- Momento de redacción (incorporar en
deck.json) — cualquier cosa sobre contenido o entrega:- "mantenlo corto / ~5 min / una línea por diapositiva" → escribe
notesmás cortos; la pausa de la diapositiva se basa en la longitud, así que notas más cortas = una charla más rápida. "ve a fondo" →notesmás ricos. - "di ‹X› en la diapositiva de precios", "empieza con un chiste", "enfatiza ‹Y›" → pon esa línea en los
notesde esa diapositiva específica para que se diga exactamente donde se pretende. - "salta la diapositiva de la hoja de ruta" → elimínala/fusiónala mientras redactas.
- "mantenlo corto / ~5 min / una línea por diapositiva" → escribe
- Política de conducción en vivo (tú la aplicas mientras se ejecuta) — cualquier cosa sobre reaccionar en la sala:
- "no respondas preguntas sobre ‹Z› / precios / personal" → cuando llegue esa pregunta a través de
heard.jsonl, NO la respondas: responde con una breve evasiva ({"cmd":"say","text":"Buena pregunta — hablemos de eso fuera de línea."}) en lugar de una respuesta real. "aplaza todas las preguntas hasta el final" → reconoce y sigue presentando en lugar de responder a mitad de la presentación. - "pausa en la diapositiva 3 para discutir", "avanza solo cuando yo lo diga" → ajusta con qué entusiasmo envías
next/present. Mantén una nota mental breve de estas reglas para toda la sesión — persisten durante la llamada, no solo en la primera diapositiva. Si una solicitud es ambigua, pregunta al usuario antes de lanzar.
- "no respondas preguntas sobre ‹Z› / precios / personal" → cuando llegue esa pregunta a través de
2 · (opcional) Vista previa — present.py --local --deck <presentación> imprime una URL de localhost para verla antes de lanzarla en vivo.
3 · Lanza en vivo, en segundo plano — python scripts/present.py "<url>" --deck <presentación> &
(el nombre/voz provienen de ~/.agentcall/config.json; --name/--voice anulan por ejecución).
El bot tarda de 30 a 90 segundos en aparecer, luego saluda y espera.
4 · Condúcelo — empieza a monitorear inmediatamente. Sigue el final de link/heard.jsonl y responde en link/commands.jsonl
(protocolo completo en Control por voz). No comenzará hasta que respondas present a un "adelante".
5 · Termina — abandona automáticamente y deja de facturar cuando todos se van, al alcanzar el límite de tiempo, o con un comando leave. Si lo iniciaste, asegúrate de que el proceso salga.
Dos modos (esta es la idea clave)
| Modo | Qué hace | Predeterminado para |
|---|---|---|
| show | Renderiza las PÁGINAS/diapositivas REALES del documento en imágenes y las muestra sin cambios | .pptx/.ppt, y PDFs con forma de diapositiva |
| generate | Analiza el documento, luego TÚ redactas una presentación significativa (títulos, viñetas, narración hablada) e incorporas las figuras propias de la fuente | .docx/.doc, PDFs densos/de informes, y temas |
Regla general: un archivo que ya es una presentación de diapositivas → muéstralo. Un documento (prosa) → genera una presentación a partir de él. auto (el predeterminado) decide por tipo de archivo, y para PDFs por la forma de la página (apaisado + texto escaso = una presentación → mostrar; retrato + denso = un documento → generar). Anula con --mode show|generate. La intención del usuario siempre gana ("presenta mis diapositivas exactamente" → mostrar; "resume esto en una presentación" → generar).
A) Mostrar una presentación tal cual (PowerPoint, o un PDF estilo diapositiva)
El modo show mantiene el diseño real de cada diapositiva (una imagen a sangre de la diapositiva real). Lo que dice depende de si el archivo lleva notas del orador:
python scripts/doc_to_deck.py "/ruta/presentacion.pptx" # renderizar diapositivas + detectar notas
- Tiene notas del orador en cada diapositiva (
.pptx) → son la narración. Solo presenta:python scripts/present.py "<URL_DE_REUNION>" --deck decks/presentacion/presentacion.json - Sin notas — o notas solo en ALGUNAS diapositivas → la presentación está marcada como
needs_narration(las diapositivas sin notas se mostrarían en completo silencio). Redacta una línea denoteshablada para cada diapositiva que carezca de una (desdedecks/<name>/source.json+ las imágenes de las diapositivas), luego presenta eldeck.jsonredactado. Esto es lo que lo convierte en un presentador y no en un lector de pantalla.
present.py SE NIEGA a presentar una presentación needs_narration hasta que cada diapositiva tenga notes (sale con un error señalando source.json). NO hay respaldo de "leer el texto de la diapositiva en voz alta" — por diseño. Así que nunca entregues un archivo sin notas sin procesar a present.py esperando que hable: convierte, redacta las notes, luego presenta el deck.json redactado. El rechazo es la red de seguridad; redactar es el trabajo.
B) Generar una presentación significativa (Word, PDF denso, o un tema)
Un documento no son diapositivas — mostrar sus páginas hace una mala charla. Así que tú construyes la presentación.
- Convierte para obtener el contenido fuente + figuras:
python scripts/doc_to_deck.py "/ruta/archivo.docx" --mode generate # escribe decks/<name>/deck.json — un borrador mecánico con notes VACÍOS, marcado needs_narration; # present.py SE LO NIEGA hasta que redactes los notes (ese es el siguiente paso, no opcional) # y decks/<name>/source.json ← las secciones analizadas + imágenes extraídas, para que redactes a partir de ellas # y decks/<name>/img/ ← las figuras propias del documento, ya extraídas - Redacta
deck.jsona partir desource.json— esta es la parte importante. Hazlo bien:- Primero esquema, luego rellena. Haz una diapositiva por idea principal. Construye una lista de verificación mental de las secciones/encabezados del documento y asegúrate de que cada punto clave aterrice en una diapositiva — no omitas cosas.
- Cada diapositiva: un
titlecorto, ≤6bulletscortos, ynotes= narración hablada natural (1–4 oraciones; los acrónimos deletreados fonéticamente como "A.P.I." para que el TTS los diga correctamente). - Reutiliza las figuras de la fuente.
source.jsonenumera las imágenes extraídas del documento (ensections[].imagesyall_images). Pon la relevante en el campoimagede una diapositiva — la diapositiva entonces muestra tus viñetas junto a esa figura real (un diseño dividido). No inventes imágenes. - Abre con una diapositiva de introducción de una línea; cierra con un resumen (el bot se va después de la última diapositiva).
- Vista previa y presenta (secciones C y D). Para un tema sin archivo, omite la conversión y redacta
decks/<name>.jsondirectamente.
Esquema JSON de la presentación (diapositiva de texto, diapositiva de imagen, o ambas juntas):
{
"title": "Mi Charla",
"slides": [
{ "title": "Introducción", "notes": "Introducción hablada." },
{ "title": "Un punto", "bullets": ["frase corta", "otra"], "notes": "Narración." },
{ "title": "Con una figura", "bullets": ["lo que muestra"], "image": "fig1.png", "notes": "Narración." },
{ "image": "slide3.png", "notes": "Una diapositiva real a sangre (modo show)." }
]
}
(bullets/notes/image son todos opcionales; alias points→bullets, say→notes; una diapositiva solo con título es una portada.)
C) Vista previa (recomendada)
python scripts/present.py --local --deck decks/<name>/deck.json # o decks/<name>.json, o un archivo sin procesar
Imprime una URL http://localhost:PORT/?ws=local — ábrela para ver las diapositivas renderizarse y avanzar automáticamente, sin reunión.
D) Presentar en vivo
python scripts/present.py "<URL_DE_REUNION>" --deck <archivo-o-presentacion> [--mode show|generate]
Las reuniones en vivo son interactivas por defecto (basadas en consentimiento): el bot se une, se presenta y espera hasta que alguien le dice que comience. Dos formas de dirigirlo:
- Por voz → enrutado a TI (el cerebro). NO hay coincidencia de palabras clave en el código. Todo lo que un participante dice — una vez que se dirige al bot por su nombre, o durante una breve ventana de seguimiento — se te entrega para que lo interpretes, y tú respondes con un comando. Protocolo a continuación.
- Por la página de control complementaria (directo). Una página de teléfono/navegador (Anterior / Pausa / Siguiente / tocar-diapositiva / Reiniciar / Descartar) cuyo enlace el bot deja en el chat de la reunión, y TAMBIÉN imprime en la consola (
▸ Página de controles: …) — transmite la URL de la consola al usuario directamente; la entrega en el chat de Meet puede no ser fiable. Los botones son inequívocos y actúan en el proceso, al instante (no pasan por ti), por lo que son el respaldo fiable y la forma de conducir sin un agente adjunto.
El bot abandona automáticamente y deja de facturar cuando todos los demás se van, al alcanzar un límite máximo, o en una salida limpia — un bot huérfano no puede acumular costos. Añade --auto para presentar inmediatamente sin preguntar; --pace <s> establece el intervalo entre diapositivas.
Control por voz — TÚ eres el cerebro (la parte importante)
En modo interactivo, el bot reenvía lo que escucha a un archivo enlace y ejecuta el comando que escribes de vuelta. Sin frases predefinidas: tú entiendes la solicitud y decides la acción. Ejecútalo en segundo plano y en bucle:
- Inícialo (interactivo es el predeterminado para en vivo):
python scripts/present.py "<url>" --deck <archivo> &Imprime dos rutas:link/heard.jsonl(bot → tú) ylink/commands.jsonl(tú → bot). Empieza a monitorear inmediatamente — el saludo se reproduce solo, pero la presentación no comenzará hasta que respondas al primer "adelante". Lee solo las líneas NUEVAS (rastrea un desplazamiento de byte/línea, o bloquea en el archivo — no vuelvas a procesar líneas viejas), y responde dentro de ~45s (después de eso la presentación se reanuda por sí sola). La forma eficiente, similar a eventos, de monitorear, sin sondeo constante:(tail -n +1 -f link/heard.jsonl # transmite cada nueva expresión como una línea; manéjala, luego añade tu respuesta a link/commands.jsonl&/tailson POSIX — en Windows usa tu instalación de ejecución en segundo plano yGet-Content link/heard.jsonl -Wait.) present.py ejecuta lo que añadas acommands.jsonlen aproximadamente 0,3 s. - Cuando el bot es llamado por su nombre ("Presenter, …") — o durante la