Especificaciones — Podbook
Expediente técnico y diseño. Este documento conserva los estudios y la arquitectura prevista. Es posible que no todas las funciones descritas estén disponibles; el guía del usuario y el código especifican la operación actual.
Versión 2, local primero. Compañero de VIABILIDAD.md, que justifica las elecciones, y MOTORES.md, que cataloga los modelos.
1. Principios
Un libro, una posición, tres formas de acceder a él. Leer, escuchar la narración, escuchar el resumen son tres miradas de un mismo objeto, no tres características. Nunca tenemos que mirar dónde estábamos.
Todo se elabora con antelación, en casa. La traducción y el audio se realizan todas las noches, en Mac, de forma gratuita. En el coche, en el tren, en un túnel, todo está ya en el aparato. Ninguna funcionalidad debería requerir la red cuando sea necesaria.
La biblioteca Calibre es la fuente de la verdad y es intocable. Podbook lo lee, nunca escribe en él y almacena sus propios datos junto a él. Puedes desinstalar Podbook sin perder nada.
Los derivados son desechables. Traducciones, audio, alineaciones: todo se puede regenerar a partir del libro y meta.json. Nada tiene valor excepto las posiciones, las anotaciones y el vocabulario, que son diminutos y versionados.
La nube es una opción, nunca una necesidad. Cada procesamiento tiene una implementación local que funciona. Los conectores API están deshabilitados por defecto.
2. Los tres componentes
2.1 Taller Podbook — macOS
La herramienta que hace el trabajo. Una línea de comando ejecutable Swift, lanzada por un agente launchd por la noche, y luego se combina con una pequeña aplicación de barra de menú si surge la necesidad. Primero en la línea de comando porque es más robusta, más fácil de depurar y se puede planificar en tres líneas.
Qué hace:
- monitorea la biblioteca Calibre y detecta nuevas funciones;
- se convierte a EPUB que no lo es, a través de
ebook-convert; - analiza, normaliza
book.json, aplica OCR a la imagen PDF; - traducido: paso rápido OPUS-MT, luego ocúpate del LLM local con glosario;
- crea la narración y calcula las alineaciones;
- escribe guiones de podcasts y los sintetiza en audio;
- publica todo en
Podbook/en Nextcloud.
Sin límite de memoria, modelos de tamaño completo, máquina enchufada: aquí es donde debe residir la mayor parte del cálculo.
podbook scan # détecte les nouveautés dans la bibliothèque
podbook process 42 --all # chaîne complète sur un livre
podbook process 42 --translate --engine mlx:qwen3-30b
podbook narrate 42 --voice kokoro:ff_siwis
podbook digest 42 --format chapter --angle apply
podbook sync # pousse vers Nextcloud
podbook status # état de traitement de la bibliothèque
2.2 Podbook — iPadOS y iOS
La aplicación de lectura, universal, objetivo mínimo iOS 18 (para iPhone XS y para el marco de traducción).
En iPad, tiene la misma cadena de procesamiento que el taller, con modelos más pequeños: un libro importado en movimiento se puede procesar sin el Mac. En iPhone, los motores pesados no están entre las opciones: la aplicación no ofrece lo que no puede hacer.
2.3 Paquetes compartidos
Módulos Swift locales, comunes a Mac y iOS, de modo que cada hito pueda probarse de forma aislada y no exista ningún código de procesamiento duplicado.
| Paquete | Responsabilidad |
|---|---|
CalibreKit | Lectura metadata.db, estructura de árbol, coberturas, cliente OPDS, llamadas a ebook-convert |
BookKit | Análisis EPUB, PDF, CBZ, texto. LOC. Normalización a book.json. Anclaje de posiciones estables |
EngineKit | Protocolos TranslationEngine, NarrationEngine, DigestEngine, la política de registro y selección |
TranslationKit | Implementaciones: Apple, OPUS-MT, MLX local, compatible OpenAI, Anthropic. Caché por huella digital, glosario |
NarrationKit | Implementaciones: AVSpeechSynthesizer, Kokoro, Piper, ElevenLabs. Generación de archivos, tablas de alineación. |
DigestKit | Guiones de resúmenes y podcasts: desglose, formatos, ángulos, indicaciones orales |
SidecarKit | Árbol de lectura y escritura Podbook/, huellas dactilares, versiones, invalidación |
SyncKit | Cliente WebDAV Nextcloud, registros de eventos de solo agregar, descarga bajo demanda |
PlayerKit | AVQueuePlayer, sesión de audio, Reproducción en curso, controles remotos, App Intents, modo automóvil |
ReaderUI | Representación Readium y PDFKit, vistas bilingües, tipografía, temas, gestos |
Jobs | La cola de tareas persistió, idempotente, reanudable. BGProcessingTaskRequest lado iOS |
3. Motores, en código
Todo tratamiento pasa por un protocolo, con sus requisitos declarados. La política de selección toma el dispositivo, las preferencias y la disponibilidad, y elige. Esto es lo que permite ejecutar el mismo código en un Mac con un modelo 30B y en un iPhone XS con el marco de Apple.
enum EngineTier { case appleBuiltIn, onDeviceModel, localNetwork, cloud }
struct EngineRequirements {
var minOSVersion: OperatingSystemVersion
var minMemoryBudget: UInt64 // ce qu'il faut pouvoir allouer
var needsNetwork: Bool
var needsCredential: CredentialKind?
var platforms: Set<Platform>
}
protocol TranslationEngine: Sendable {
static var id: String { get } // "apple", "opus-mt", "mlx:qwen3-8b", …
static var tier: EngineTier { get }
static var requirements: EngineRequirements { get }
func translate(_ blocks: [Block],
glossary: inout Glossary) async throws -> [BlockTranslation]
}
NarrationEngine y DigestEngine sigue el mismo dibujo. Tres consecuencias útiles:
- La aplicación sabe lo que puede hacer. La configuración muestra los motores disponibles en esto dispositivo, y atenúe los demás con el motivo (“solicitar iOS 26”, “solicitar 5 GB de memoria”).
- Un nuevo proveedor es una implementación, no un rediseño. El conector compatible con OpenAI cubre Mammouth.ai, OpenRouter, OpenAI y LM Studio o Ollama en el Mac.
- Se rastrea la procedencia. Cada bloque traducido lleva el identificador del motor y su versión, lo que permite una mejora progresiva de la calidad y una nueva visualización honesta (“este párrafo proviene del pase rápido”).
4. Formato de intercambio
4.1 Estructura de árbol
Nextcloud/
CalibreLibrary/ ← intouchée, propriété de Calibre
metadata.db
Auteur/Titre (42)/livre.epub
Podbook/
42/
book.json structure normalisée
fr.json traduction, provenance par bloc
narration/
ch01.m4a
ch01.align.json phrase → intervalle de temps
digest/
ch01-resume.m4a
ch01-resume.json script, angle, alignement du transcript
book-20min.m4a + .json
meta.json empreintes, états, versions de moteur
state/
mac.jsonl journal en ajout seul
ipad.jsonl
iphone.jsonl
vocabulary.jsonl
4.2 book.json
El modelo estandarizado, común a todos los formatos: es éste el que permite utilizar una única cadena de procesamiento para un EPUB como para un PDF escaneado.
{
"calibreId": 42,
"title": "…", "author": "…", "language": "en",
"sourceFile": { "path": "…", "sha256": "…" },
"chapters": [{
"index": 0, "title": "…",
"anchor": { "type": "readiumLocator", "value": "…" },
"blocks": [{
"index": 0,
"type": "paragraph", // heading | paragraph | quote | code | image | list
"text": "…",
"hash": "…", // empreinte : clé de cache et d'invalidation
"sentences": [{ "range": [0, 142] }]
}]
}]
}
4.3 fr.json y alineación
// fr.json — une entrée par bloc traduit
{ "0/0": { "text": "…", "engine": "mlx:qwen3-30b", "engineVersion": "1.2",
"sourceHash": "…", "at": "2026-11-02T03:14:00Z" } }
// ch01.align.json — le pont lecture ↔ écoute
{ "audio": "ch01.m4a", "duration": 1843.2,
"spans": [{ "block": 0, "sentence": 0, "start": 0.0, "end": 4.12 }] }
sourceHash es la clave de todo: si el bloque fuente cambia, su traducción y audio se invalidan automáticamente y no se recalcula nada innecesariamente.
4.4 Posiciones: iniciar sesión únicamente
Con tres dispositivos y un Nextcloud, sobrescribir un archivo compartido hará que pierdas una posición de reproducción en algún momento. Por lo tanto, cada dispositivo escribe como su propio periódico, agregado solo, y cada uno fusiona todos los registros al leer, conservando el evento más reciente por libro.
// state/ipad.jsonl
{"t":"2026-11-02T22:14:03Z","device":"ipad","book":42,"kind":"position",
"chapter":7,"block":128,"char":44,"source":"reading"}
{"t":"2026-11-03T07:51:10Z","device":"iphone","book":42,"kind":"position",
"chapter":7,"block":203,"char":0,"source":"listening","audioTime":612.4}
No hay conflictos posibles, implementación trivial y se conserva el historial. Mismo mecanismo para anotaciones y vocabulario.
5. Cadena de procesamiento
Asincrónico, idempotente, repetible en cada paso. Puede finalizar el proceso en medio del trabajo y comenzar de nuevo.
détection dans Calibre
→ conversion vers EPUB si nécessaire [ebook-convert, Mac]
→ analyse → book.json
→ OCR si PDF image [Vision]
→ découpage en phrases
→ traduction, passe rapide [OPUS-MT — minutes]
→ traduction, passe soignée [LLM local — 40-80 min Mac]
→ narration par chapitre [AVSpeech ou Kokoro]
→ tables d'alignement
→ scripts de résumé et de podcast [LLM local]
→ synthèse audio des podcasts
→ indexation plein texte
→ publication vers Nextcloud
Cada paso escribe su resultado y marca su estado en meta.json. Nada es obligatorio: un libro puede permanecer en versión original sin audio. El usuario ve el progreso por libro y puede activar o cancelar cada paso por separado.
El aumento gradual de la calidad es una elección de diseño, no un efecto secundario. El pase rápido hace que el libro sea legible en bilingüe esa misma noche; El pase cuidadoso reemplaza los bloques uno por uno durante la noche. La aplicación muestra discretamente el origen y puedes pedir que se repita un pasaje que suene mal.
6. Características
6.1 Biblioteca
Vista nativa Calibre: series, etiquetas, notas, columnas personalizadas, portadas. Pastillas de estado por libro: traducidas, narradas, en podcast, disponibles sin conexión. Filtros, colecciones, búsqueda de texto completo en un libro y en toda la biblioteca. Importación única fuera de Calibre: archivos, hoja compartida, AirDrop.
6.2 Lector
Seis modos de visualización, conmutables con un gesto sin perder tu lugar:
| Moda | Descripción | Cuando |
|---|---|---|
| Sólo VO | Texto original | Lectura normal |
| FR solo | Traducción completa | Fatiga, libro difícil |
| Alternativo | Párrafo VO luego su traducción, en gris más pequeño | Aprender a leer |
| Dos columnas | VO a la izquierda, FR a la derecha, párrafos alineados | iPad en paisaje |
| Revelación disponible | Solo VO, la traducción de una oración aparece como apoyo | Modo predeterminado recomendado |
| Diadema | Solo VO, banner fijo en la parte inferior para el párrafo actual | Leyendo sobre la marcha |
Pulsa sobre una palabra: definición, traducción, fonética, adición al cuaderno. Pulsación prolongada de una frase: traducción inmediata y sin conexión utilizando el framework de Apple. incluido en el iPhone XS. Destacados, notas, marcadores. Tipografía completa, fuentes aptas para dislexia, temas claros, sepia y oscuros.
6.3 Escuchar
Narración en original o francés, desde cualquier parte del libro. Velocidad de 0,5× a 3× con corrección de altura. Resaltado seguido por voz y desplazamiento automático. Saltos de 15 y 30 segundos, salto de capítulo, temporizador de apagado. Archivo mixto: capítulos narrados, resúmenes, podcasts, audiolibros ya en propiedad. Repetición exacta en ambas direcciones con posición de reproducción.
6.4 Resúmenes y podcasts
Cinco formatos: capítulo flash (3 min), resumen del capítulo (8–12 min), el libro en 20 minutos, conversación bidireccional, temática en profundidad. Cuatro ángulos: resumen fiel, ideas clave y aplicación práctica, explicación para principiantes, lectura crítica.
Transcripción mostrada y en la que se puede hacer clic: al escribir una oración se abre el libro en el pasaje correspondiente. Regeneración con otro ángulo u otra voz, sin perder la versión anterior. Posibilidad de hacer una pregunta sobre el libro y obtener una respuesta hablada.
No compartir ni exportar los audios generados. Un resumen es una obra derivada: producida para uno mismo a partir de un libro de su propiedad, es para uso privado; transmitirlo no lo es. La falta de un botón para compartir es una elección, no un descuido.
6.5 Modo coche
Interfaz de tres objetivos táctiles en pantalla completa: reproducir /pause, anterior, siguiente. Nada más. Activación automática al conectar un dispositivo Bluetooth designado. Archivo construido de antemano que se sucede sin intervención: destello del capítulo siguiente, narración, capítulo siguiente. Mandos al volante, visualización en la pantalla del vehículo, control por Siri. Indicador claro de lo que está disponible sin conexión antes para salir.
6.6 Vocabulario
Palabras y frases guardadas con su contexto original: el libro, el capítulo, la oración. Repaso ligero y espaciado, unos minutos al día. Exportar Anki.
6.7 Configuración
Elección del motor por procesamiento, con visualización de lo que está disponible en este dispositivo y por qué el resto no. Dirección de Nextcloud y ruta de la biblioteca Calibre. Punto de acceso compatible con OpenAI (predeterminado: Mac en la red local). Teclas API opcionales, en Keychain. Presupuesto mensual con mostrador y techo de bloqueo. Condiciones de tramitación: Sólo Wi-Fi, sólo red, sólo noche. Gestión de almacenamiento: peso por libro, purga de audio de libros completos, calidad de codificación.
7. Detalles técnicos
- Swift 6, SwiftUI, competencia estricta. Objetivo mínimo iOS / iPadOS 18.0, macOS 15. Las funciones que dependen de iOS 26 son opcionales, tras una prueba de disponibilidad, con respaldo.
- Modelos locales : MLX Swift para LLM, CoreML u ONNX Runtime para OPUS-MT y Kokoro. Descargado a pedido desde la configuración, no incrustado en el binario, almacenado fuera de la copia de seguridad iCloud.
- Memoria : autorización
com.apple.developer.kernel.increased-memory-limiten la aplicación iOS, con respaldo propio si se rechaza. La política de selección de motores cuestiona el presupuesto real antes de proponer un modelo. - Audio :
UIBackgroundModes: audio,AVAudioSessionenplaybackcon opción.spokenAudio. AAC mono 32–48 kbit/s, aproximadamente 15 MB por hora. - Almacenamiento : catálogo, traducciones y alineamientos en SQLite vía GRDB. Archivos en el contenedor de la aplicación, no en el temporal.
- Secretos : Keychain únicamente. Nunca en binario, nunca en repositorio.
- Calibre :
metadata.dbabrir como solo lectura, exclusivamente. Posible escritura del estado víacalibredb, nunca vivas.
8. Hoja de ruta
Hitos breves, cada uno de los cuales ofrece algo utilizable por sí solo.
| Hito | Contenido | Duración | Lo que ganamos |
|---|---|---|---|
| 0 — Medidas | Techo de memoria iPad, prueba de traducción ciega, escuchando a Kokoro | 1–2 días | Las opciones de toda la suite |
| 1 — Base Calibre y lector | CalibreKit, biblioteca, lector EPUB y PDF, tipografía, temas, posición persistente | 2–3 semanas. | Leo mis libros, con mis metadatos |
| 2 — muleta francesa | Traducción de Apple, toque en frase, toque en palabra, diccionario, los seis modos bilingües, vocabulario | 1–2 semanas. | La sesión de lectura vespertina — y funciona en el iPhone XS |
| 3 — Taller v1 y Nextcloud | CLI macOS, ebook-convert, book.json, pasa OPUS-MT, SidecarKit, SyncKit, registros de posición | 2–3 semanas. | Todos los formatos, totalmente bilingüe, tres dispositivos sincronizados |
| 4 — Escucha | Narración AVSpeech, alineación, audio de fondo, comandos bloqueados, taller pregenerado | 2–3 semanas. | Escucho mi libro en el auto |
| 5 — Calidad local | MLX en el taller, pase cuidadoso con glosario, mejora progresiva de calidad, Kokoro | 2–3 semanas. | Lectura cómoda y buenas voces, por 0€ |
| 6 — Pódcasts | DigestKit, los cinco formatos, los cuatro ángulos, cola de escucha, transcripción en la que se puede hacer clic | 2–3 semanas. | El libro en 20 minutos |
| 7 — Modo coche | Interfaz dedicada, cola automática, Siri, generación nocturna, indicador fuera de línea | 1–2 semanas. | Ya no toco el teléfono |
| 8 — Conectores opcionales | Compatible OpenAI, Anthropic, ElevenLabs, Keychain, presupuesto, modo “mi Mac como servidor” | 1 semana. | Un remedio cuando las premisas no son suficientes |
| 9 — Comodidad | Canal completo en iPad, OCR, búsqueda global, exportación Anki, CarPlay si se concede | continuo | — |
Versión ya útil a diario: final del hito 4, es decir, de 8 a 11 semanas. Paquete completo: aproximadamente 3 a 4 meses a tiempo parcial.
El hito 0 es breve y no es opcional: evita basarse en una hipótesis de memoria o de calidad que resultaría falsa tres semanas después.
9. Preguntas abiertas
- ¿Qué Mac y cuánta memoria unificada? Determina el tamaño de los modelos de taller. Una serie M de 16 GB funciona cómodamente entre 8 y 12 B; con 32 GB y más, un MoE de 30 B se convierte en la opción predeterminada.
- ¿Nextcloud es autohospedado y en qué enlace ascendente? Determinante para descarga de audio: 600 MB por libro procesado, eso cuenta.
- ¿Tamaño de la biblioteca Calibre? No es lo mismo un primer tratamiento masivo con 300 kilos que con 30.
- ¿Ya existe una escala trasera o equivalente? Condiciona el modo “mi Mac como servidor” desde fuera.
- ¿Cuenta de desarrollador de Apple? 99€/an para una construcción firmada válida por un año. La firma gratuita vence cada 7 días, lo que no se puede realizar en tres dispositivos.