100 Días de Código en Python — Día 91: Proyecto de portafolio — Convertir un PDF en audiolibro

📝 Contenido original del curso#

¿Demasiado cansado para leer? Construye un script de Python que tome un archivo PDF, identifique el texto y lo convierta en voz. En la práctica, crearás un audiolibro gratis.

El texto a voz con IA ha avanzado mucho: puede sonar más natural que un audiolibro real.

Usando lo que aprendiste sobre peticiones HTTP, APIs y scripting en Python, crea un programa que convierta archivos PDF en voz.

Quizá quieras elegir tu propia API de texto a voz (TTS, Text-To-Speech). Algunas que puedes considerar: iSpeech, Google Cloud Text-to-Speech y Amazon Polly.

Pregunta de la tarea — Momento de reflexión: cómo abordaste el proyecto; qué fue difícil y qué fácil; cómo mejorarías; tu mayor aprendizaje; qué harías distinto.

Prerequisitos: archivos y rutas (Día 24); peticiones HTTP, parámetros y claves de API (Días 33–35); variables de entorno para las claves (Día 35); excepciones (Día 30); cadenas y listas (Días 2 y 4).

🔍 Antes de programar#

Arquitectura: una tubería (pipeline)#

 PDF ──► [1. Extraer texto] ──► texto crudo
                                   │
                                   ▼
                          [2. Limpiar y dividir] ──► fragmentos
                                                        │
                                                        ▼
                                             [3. Texto a voz] ──► audio

Cada etapa es una función con entrada y salida claras. Ventaja: puedes probar las etapas 1 y 2 sin internet ni claves, y cambiar el servicio de voz (etapa 3) sin tocar el resto.

🎯 Objetivo de aprendizaje#

Extraer el texto de un PDF y reconocer cuándo no es posible.

📖 Explicación conceptual#

Un PDF no guarda "párrafos" como un documento de Word: guarda instrucciones de dibujo ("escribe esta letra en esta posición"). Las librerías reconstruyen el texto a partir de esas posiciones, así que el resultado puede traer saltos de línea en mitad de frases, encabezados y números de página mezclados, o guiones de corte de palabra.

Y si el PDF es una foto escaneada, no hay letras que extraer: solo una imagen. Haría falta OCR (reconocimiento óptico de caracteres), que es otro proyecto.

🔎 Ejemplo explicado#

Instala: pip install pypdf

from pypdf import PdfReader

def extraer_texto(ruta_pdf):
    lector = PdfReader(ruta_pdf)
    paginas = []
    for pagina in lector.pages:
        texto = pagina.extract_text() or ""
        paginas.append(texto)
    return paginas

• PdfReader abre el PDF; lector.pages es la lista de páginas.
• extract_text() devuelve el texto de una página. El or "" asegura una cadena aunque venga vacía.
• Devuelve una lista por página: útil para convertir solo algunas páginas o crear un audio por capítulo.

Verificado: en un PDF de prueba, "Página dos: el año 2026 y la niñez." se extrajo completo, con tildes y "ñ". En un PDF formado solo por una imagen, el resultado fue [''].

⚠️ Errores frecuentes#

¿Por qué dividir?#

Los servicios de voz en la nube tienen un límite de caracteres por solicitud (del orden de unos pocos miles; consulta el límite exacto del servicio que elijas en su documentación). Un libro tiene cientos de miles de caracteres. Solución: dividir en fragmentos, convertir cada uno y unir los audios.

Cortar en cualquier punto partiría palabras y frases, y la voz sonaría rara. Mejor cortar al final de una oración.

def dividir_en_fragmentos(texto, maximo=4500):
    fragmentos, actual = [], ""
    for oracion in texto.replace("\n", " ").split(". "):
        oracion = oracion.strip()
        if not oracion:
            continue
        if len(actual) + len(oracion) + 2 > maximo and actual:
            fragmentos.append(actual.strip())
            actual = ""
        actual += oracion + ". "
    if actual.strip():
        fragmentos.append(actual.strip())
    return fragmentos

Cómo funciona: reemplaza saltos de línea por espacios, separa por ". ", y va acumulando oraciones en actual hasta que la siguiente no cabe; entonces guarda el fragmento y empieza otro.

Verificado: con maximo=500, un texto de unos 1700 caracteres se dividió en 4 fragmentos de 494, 494, 494 y 201 caracteres.

🐞 Esta función tiene un error (verificado): si una "oración" es más larga que maximo (por ejemplo, una tabla sin puntos), el fragmento la incluye entera y supera el límite. Lo corregirás en la sección 6.

Limpieza adicional (ideas para ti)#

• Quitar números de página y encabezados que se repiten en cada página.
• Unir palabras cortadas con guion al final de línea ("electro-\nencefalograma").
• Decidir qué hacer con URLs, tablas y notas al pie (¿leerlas? ¿omitirlas?).

Esquema para una API en la nube (patrón general, no ejecutado)#

para cada fragmento (numerado):
    preparar la solicitud: texto, idioma ("es-..."), voz, formato de audio
    enviar la solicitud con la clave (leída de una variable de entorno)
    si la respuesta es un error: registrar cuál fragmento falló y seguir o detener
    guardar el audio como parte_001.mp3, parte_002.mp3...
unir las partes o dejarlas como "pistas" del audiolibro

Cada proveedor tiene su librería oficial (por ejemplo, google-cloud-texttospeech o boto3 para Polly) y su propio formato: sigue la documentación oficial del que elijas.

Problema#

Construir un programa que convierta un PDF en un archivo de audio.

Contexto#

Un compañero con baja visión, o que tiene un trayecto largo en bus, quiere escuchar las lecturas del plan lector.

Objetivo#

Un script (o una pequeña GUI) que reciba un PDF y produzca audio, con manejo de errores y sin exponer claves.

Requisitos funcionales#

1. Recibe la ruta de un PDF (argumento, input() o diálogo de archivos).
2. Permite elegir un rango de páginas.
3. Avisa si el PDF no tiene texto.
4. Genera uno o varios archivos de audio numerados.

Restricciones técnicas#

• Las tres etapas en funciones separadas; las dos primeras con pruebas.
• Claves solo en variables de entorno.
• Solo PDF con derechos para convertir (ver abajo).

Derechos de autor#

Convertir en audio un libro con derechos de autor para compartirlo es ilegal en la mayoría de países. Para practicar, usa textos de dominio público (por ejemplo, obras clásicas de autores fallecidos hace décadas, según la ley de cada país) o documentos que tú escribiste.

Planificación#

1. Comprender (escucha un audiolibro de dominio público). 2. Entradas: PDF y rango. 3. Procesos: las tres etapas. 4. Salidas: audios. 5. Dividir en funciones. 6. Elegir el servicio de voz. 7. Implementar. 8. Probar. 9. Corregir. 10. Mejorar.

Construcción paso a paso#

• Versión 1 — Extraer: imprimir el texto de un PDF y guardarlo en texto.txt (encoding="utf-8").
• Versión 2 — Preparar: dividir en fragmentos; corregir el error de las oraciones largas (ver depuración).
• Versión 3 — Voz local: convertir un fragmento con una opción local.
• Versión 4 — Libro completo: todos los fragmentos, archivos numerados, progreso en pantalla.
• Versión 5 — Nube (opcional, con autorización): la misma interfaz con una API.
• Versión final: rango de páginas, manejo de errores, README.md y diario.

Pruebas#

fragmentos = dividir_en_fragmentos("a" * 1200, 500)
assert all(len(f) <= 500 for f in fragmentos)   # hoy falla: corrígelo

🧪 Prueba y depuración#

1. Haz pasar la prueba 5. Pistas: si una oración es más larga que maximo, pártela por espacios (palabras); si una palabra sola es más larga, córtala por caracteres. ¿Dónde agregas esa lógica sin romper las pruebas 3 y 4?
2. Encuentra los tres problemas:

import requests
CLAVE = "AIzaSy...mi_clave_real"
texto = open("libro.pdf").read()
respuesta = requests.post(URL, json={"texto": texto, "clave": CLAVE})
open("libro.mp3", "w").write(respuesta.text)

(La clave está escrita en el código; un PDF no se lee como texto plano con open().read(); y el audio es binario: se guarda con "wb" y respuesta.content. Además, no se revisa respuesta.status_code ni el límite de caracteres.)

⭐ Extensión del proyecto#

• 🟢 Reto 1 — Aplicación: elegir la velocidad de lectura y la voz (en pyttsx3: propiedades rate y voice).
• 🟡 Reto 2 — Ampliación: un audio por capítulo, detectando títulos como "Capítulo" en el texto.
• 🟠 Reto 3 — Desafío: interfaz Tkinter con barra de progreso que no se congele (convierte por partes con after, o investiga threading).
• 🔴 Reto 4 — Pensamiento computacional: si la conversión se interrumpe en el fragmento 57 de 120, ¿cómo continúas sin repetir los 56 anteriores ni pagar dos veces? Diseña un archivo de "estado" y pruébalo interrumpiendo el programa.

Situación#

El área de inclusión del colegio necesita convertir las guías de estudio (PDF hechos por los docentes, con su autorización) en audios para estudiantes con dificultades de lectura o baja visión.

Requisitos#

1. Procesar una carpeta de PDF y generar un audio por guía.
2. Crear un indice.html con la lista de audios reproducibles (<audio controls>), accesible con teclado.
3. Omitir de la lectura los encabezados repetidos y los números de página.

Decisiones que debes tomar (y justificar)#

• ¿Cómo describes las imágenes y tablas de la guía, que no se pueden "leer"?
• ¿Cómo validas con un usuario real que el audio es útil?

Casos de prueba#

• Una guía escaneada aparece en un reporte de "no convertibles".
• El índice funciona sin ratón.

Conceptuales#

1. ¿Por qué un PDF escaneado no tiene texto extraíble?
2. ¿Por qué hay que dividir el texto antes de enviarlo a una API de voz?
3. ¿Qué ventaja tiene separar el programa en tres etapas?
4. ¿Por qué el audio se guarda con "wb"?

Análisis de código#

texto = pagina.extract_text() or ""

¿Qué pasa si extract_text() devuelve None? ¿Y si devuelve "Hola"?

Predicción#

¿Cuántos fragmentos produce dividir_en_fragmentos("Hola. Chao. Bien.", 8)? Razónalo y luego compruébalo. Fíjate bien en el último fragmento: el resultado verificado es ['Hola.', 'Chao.', 'Bien..']. ¿De dónde sale el punto doble y cómo lo corriges?

Depuración#

"Mi programa imprime Cap�tulo en la consola." ¿El texto extraído está mal? ¿Cómo lo compruebas?

Modificación#

Cambia extraer_texto para que reciba desde y hasta (números de página empezando en 1) y extraiga solo ese rango.

Creación#

Escribe limpiar(texto) que una las palabras cortadas con guion al final de línea ("electro-\nencefalograma" → "electroencefalograma").