Saltar al contenido principal

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.

PaqueteResponsabilidad
CalibreKitLectura metadata.db, estructura de árbol, coberturas, cliente OPDS, llamadas a ebook-convert
BookKitAnálisis EPUB, PDF, CBZ, texto. LOC. Normalización a book.json. Anclaje de posiciones estables
EngineKitProtocolos TranslationEngine, NarrationEngine, DigestEngine, la política de registro y selección
TranslationKitImplementaciones: Apple, OPUS-MT, MLX local, compatible OpenAI, Anthropic. Caché por huella digital, glosario
NarrationKitImplementaciones: AVSpeechSynthesizer, Kokoro, Piper, ElevenLabs. Generación de archivos, tablas de alineación.
DigestKitGuiones de resúmenes y podcasts: desglose, formatos, ángulos, indicaciones orales
SidecarKitÁrbol de lectura y escritura Podbook/, huellas dactilares, versiones, invalidación
SyncKitCliente WebDAV Nextcloud, registros de eventos de solo agregar, descarga bajo demanda
PlayerKitAVQueuePlayer, sesión de audio, Reproducción en curso, controles remotos, App Intents, modo automóvil
ReaderUIRepresentación Readium y PDFKit, vistas bilingües, tipografía, temas, gestos
JobsLa 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:

ModaDescripciónCuando
Sólo VOTexto originalLectura normal
FR soloTraducción completaFatiga, libro difícil
AlternativoPárrafo VO luego su traducción, en gris más pequeñoAprender a leer
Dos columnasVO a la izquierda, FR a la derecha, párrafos alineadosiPad en paisaje
Revelación disponibleSolo VO, la traducción de una oración aparece como apoyoModo predeterminado recomendado
DiademaSolo VO, banner fijo en la parte inferior para el párrafo actualLeyendo 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-limit en 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, AVAudioSession en playback con 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.db abrir como solo lectura, exclusivamente. Posible escritura del estado vía calibredb, nunca vivas.

8. Hoja de ruta​

Hitos breves, cada uno de los cuales ofrece algo utilizable por sí solo.

HitoContenidoDuraciónLo que ganamos
0 — MedidasTecho de memoria iPad, prueba de traducción ciega, escuchando a Kokoro1–2 díasLas opciones de toda la suite
1 — Base Calibre y lectorCalibreKit, biblioteca, lector EPUB y PDF, tipografía, temas, posición persistente2–3 semanas.Leo mis libros, con mis metadatos
2 — muleta francesaTraducción de Apple, toque en frase, toque en palabra, diccionario, los seis modos bilingües, vocabulario1–2 semanas.La sesión de lectura vespertina — y funciona en el iPhone XS
3 — Taller v1 y NextcloudCLI macOS, ebook-convert, book.json, pasa OPUS-MT, SidecarKit, SyncKit, registros de posición2–3 semanas.Todos los formatos, totalmente bilingüe, tres dispositivos sincronizados
4 — EscuchaNarración AVSpeech, alineación, audio de fondo, comandos bloqueados, taller pregenerado2–3 semanas.Escucho mi libro en el auto
5 — Calidad localMLX en el taller, pase cuidadoso con glosario, mejora progresiva de calidad, Kokoro2–3 semanas.Lectura cómoda y buenas voces, por 0€
6 — PódcastsDigestKit, los cinco formatos, los cuatro ángulos, cola de escucha, transcripción en la que se puede hacer clic2–3 semanas.El libro en 20 minutos
7 — Modo cocheInterfaz dedicada, cola automática, Siri, generación nocturna, indicador fuera de línea1–2 semanas.Ya no toco el teléfono
8 — Conectores opcionalesCompatible OpenAI, Anthropic, ElevenLabs, Keychain, presupuesto, modo “mi Mac como servidor”1 semana.Un remedio cuando las premisas no son suficientes
9 — ComodidadCanal completo en iPad, OCR, búsqueda global, exportación Anki, CarPlay si se concedecontinuo—

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​

  1. ¿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.
  2. ¿Nextcloud es autohospedado y en qué enlace ascendente? Determinante para descarga de audio: 600 MB por libro procesado, eso cuenta.
  3. ¿Tamaño de la biblioteca Calibre? No es lo mismo un primer tratamiento masivo con 300 kilos que con 30.
  4. ¿Ya existe una escala trasera o equivalente? Condiciona el modo “mi Mac como servidor” desde fuera.
  5. ¿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.