factreel 0.1.0__tar.gz

factreel-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,27 @@
+name: Bug report / Error
+description: Something doesn't work / Algo no funciona
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened? / ¿Qué pasó?
+      description: Command you ran and what you expected.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `factreel doctor`
+      render: text
+  - type: textarea
+    id: log
+    attributes:
+      label: Log (logs/factreel_YYYY-MM.log), without API keys
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: factreel --version, OS and Python version
+    validations:
+      required: true

factreel-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

factreel-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature or provider request / Propuesta
+description: Idea, new language, new voice/image provider or uploader
+labels: [enhancement]
+body:
+  - type: textarea
+    id: idea
+    attributes:
+      label: What would you like? / ¿Qué te gustaría?
+    validations:
+      required: true
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd like to implement it myself / Me gustaría implementarlo yo

factreel-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,6 @@
+## What and why / Qué y por qué
+
+## Checklist
+- [ ] Tests added or updated (`pytest` passes)
+- [ ] `ruff check .` passes
+- [ ] Docs / CHANGELOG updated if behaviour changed

factreel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install FFmpeg (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Install FFmpeg (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ffmpeg
+      - name: Install FFmpeg (Windows)
+        if: runner.os == 'Windows'
+        uses: FedericoCarboni/setup-ffmpeg@v3
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - name: Tests
+        shell: bash
+        run: |
+          set -o pipefail
+          pytest -q -rf --tb=line 2>&1 | tee pytest.log || { grep -E "^(FAILED|E |/|.*Error)" pytest.log | head -15 | sed 's/^/::error::/'; ffmpeg -hide_banner -filters 2>/dev/null | grep -E " (ass|xfade|loudnorm) " | sed 's/^/::warning::filter /'; exit 1; }
+      - name: End-to-end preview video
+        run: |
+          factreel init demo --lang es
+          factreel make -c demo --offline --voice dummy --no-history

factreel-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing, no API token needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

factreel-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.env
+.factreel/
+client_secrets.json
+*.mp4
+!docs/*.mp4

factreel-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-20
+
+### Added
+- First public release, extracted from a channel that publishes a Short every day.
+- Fact-grounded script writer for any OpenAI-compatible LLM, with number, repetition and rumour guards,
+  a fact-check pass and a facts-only fallback.
+- Voice chain: Edge, ElevenLabs, Cloudflare Aura, system voice, dummy; health tracking.
+- Image chain: Cloudflare FLUX, NVIDIA FLUX, custom command, archive, procedural gradient.
+- Word-by-word ASS subtitles, jitter-free zoom, cross-fades, loudness normalisation, music with credits.
+- Spanish and English templates; `init`, `make`, `topics`, `doctor`, `upload`, `run` commands.
+- Optional YouTube upload with synthetic-media declaration.
+- Works with FFmpeg builds without libass (e.g. Homebrew's `ffmpeg`): the video is rendered without burned
+  subtitles and a warning explains how to get a full build.

factreel-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be kind, assume good intent, welcome newcomers and people of every background and language,
+and keep discussions about the work. Report unacceptable behaviour privately to the maintainer through
+[GitHub](https://github.com/DeadY2J) (or a private security advisory); reports are handled confidentially.

factreel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to FactReel
+
+Thanks for helping! Issues and pull requests are welcome **in English or Spanish** (también en español).
+
+## Setup
+
+```bash
+git clone https://github.com/DeadY2J/factreel
+cd factreel
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev,youtube]"
+pytest            # needs ffmpeg for the end-to-end test (it is skipped otherwise)
+ruff check .
+```
+
+Try your change on a real channel without spending API credits:
+
+```bash
+factreel init /tmp/test-channel --lang es
+factreel make -c /tmp/test-channel --offline --voice dummy --no-history
+```
+
+## Good first contributions
+
+- **A new language**: add an entry to `LANGS` in `src/factreel/lang.py` (prompts, month names, call-to-action
+  regex, default Edge voice), a template in `src/factreel/templates/<lang>/` and a test.
+- **A new voice or image provider**: see [docs/providers.md](docs/providers.md).
+- **A new uploader** (TikTok, Instagram Reels…): mirror `src/factreel/youtube.py`.
+- Anything in the [roadmap](ROADMAP.md) or labelled `good first issue`.
+
+## Guidelines
+
+- Keep the guarantees: never let the script state something that isn't in the facts, never block a video
+  because one optional service is down, never put secrets in config files.
+- New behaviour needs a test. Network calls must be mockable; tests must pass offline.
+- Keep dependencies light: optional features go in an extra (`[project.optional-dependencies]`).
+- Format with `ruff`. One topic per pull request, with a short description of the why.
+
+By contributing you agree that your contributions are licensed under the MIT license.

factreel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Lamelas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

factreel-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: factreel
+Version: 0.1.0
+Summary: Fact-checked faceless short videos (YouTube Shorts, TikTok, Reels) from a list of verified facts: AI script with anti-hallucination guards, voice fallback chain, karaoke subtitles and FFmpeg render.
+Project-URL: Homepage, https://github.com/DeadY2J/factreel
+Project-URL: Issues, https://github.com/DeadY2J/factreel/issues
+Project-URL: Changelog, https://github.com/DeadY2J/factreel/blob/main/CHANGELOG.md
+Author-email: Jorge Lamelas <205297977+DeadY2J@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edge-tts,faceless,fact-checking,ffmpeg,llm,reels,spanish,subtitles,text-to-speech,tiktok,video-automation,youtube-shorts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: edge-tts>=7.3.1
+Requires-Dist: pillow>=10.0
+Requires-Dist: requests>=2.31
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: youtube
+Requires-Dist: google-api-python-client>=2.100; extra == 'youtube'
+Requires-Dist: google-auth-oauthlib>=1.1; extra == 'youtube'
+Requires-Dist: google-auth>=2.23; extra == 'youtube'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# FactReel 🎬✅
+
+**Fact-checked faceless short videos, on autopilot.**
+YouTube Shorts · TikTok · Reels, from a list of verified facts, with free AI services and a fallback for everything.
+
+[![CI](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/factreel.svg)](https://pypi.org/project/factreel/)
+[![Python](https://img.shields.io/pypi/pyversions/factreel.svg)](https://pypi.org/project/factreel/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[English](README.md) · [Español](README.es.md)
+
+<img src="docs/demo.gif" width="260" alt="FactReel demo: vertical video with word-by-word subtitles">
+
+</div>
+
+---
+
+Most "AI shorts generators" let a language model make things up. **FactReel doesn't.** You write the facts
+(with sources) once; the AI only turns them into a punchy script, and every script goes through guards that
+reject invented numbers, repeated ideas, unlabelled rumours and anything a second fact-checking pass can't
+find in your facts. Then it narrates it, draws the images, burns karaoke subtitles and renders a vertical
+MP4 ready to upload.
+
+It grew out of a real channel that publishes a Short every day unattended, so it is built to **never stop
+on a bad day**: if the voice service, the image API or the script AI is down, the next option in the chain
+takes over.
+
+## Features
+
+- 🛡️ **Anti-hallucination script writer**: number whitelist, repetition check, rumour labelling, a
+  temperature-0 fact-check pass, and a facts-only fallback that is always correct.
+- 🗣️ **Voice fallback chain**: Microsoft Edge neural voices (free, no key) → ElevenLabs → Cloudflare
+  Aura → your OS's offline voice. `factreel doctor` tells you when a service is down and when it is back.
+- 🖼️ **Image fallback chain**: Cloudflare Workers AI FLUX → NVIDIA NIM FLUX → your own generator
+  (local GPU, ComfyUI…) → archive of previous images → procedural background that always works offline.
+- 💬 **Word-by-word subtitles** with the spoken word highlighted, synced from the TTS engine or Whisper.
+- 🎞️ **Smooth Ken Burns zoom without jitter** (sub-pixel rendering), cross-fades on scene changes,
+  voice normalised to -14 LUFS, optional background music with automatic credits.
+- 🌍 **Spanish and English first-class** (prompts, month names, countdowns). More languages = one dict.
+- 💸 **Free by default**: runs with zero API keys; every paid service is optional and budget-capped.
+- 🔌 **Any OpenAI-compatible LLM**: NVIDIA NIM, OpenRouter, Groq, OpenAI, Ollama, LM Studio, OmniRoute…
+- 📤 **Optional YouTube upload** with the "altered or synthetic content" flag set for you.
+- ✅ **Verifies every render** (resolution, audio, no black screen) before it reaches the upload queue.
+
+## Quick start
+
+You need **Python 3.10+** and **[FFmpeg](https://ffmpeg.org/download.html)** on your PATH.
+
+```bash
+pip install factreel
+factreel init my-channel --lang en      # or --lang es
+cd my-channel
+factreel doctor                         # checks FFmpeg, keys and every voice
+factreel make                           # -> output/20261020_180000_venus_day.mp4 (+ .json/.txt metadata)
+```
+
+That's it: with no keys at all you get a video with the free Edge voice, the facts read as they are and
+offline backgrounds. Add free keys to `.env` to unlock the AI script and AI images:
+
+| Key | What it unlocks | Cost |
+| --- | --- | --- |
+| `NVIDIA_API_KEY` ([build.nvidia.com](https://build.nvidia.com)) | AI script + fact check, FLUX images | free credits |
+| `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN` | FLUX images, backup voice, exact subtitle timing (Whisper) | 10,000 free neurons/day, capped |
+| `ELEVENLABS_API_KEY` | premium voice | optional |
+
+## How it works
+
+```mermaid
+flowchart LR
+    F[facts.json<br/>verified facts + sources] --> T[topic rotation<br/>queue.txt / least used]
+    T --> S[AI script]
+    S --> G{guards<br/>numbers · repeats<br/>rumours · fact check}
+    G -- rejected --> S
+    G -- gives up --> FB[facts-only script]
+    G -- ok --> V[voice chain]
+    FB --> V
+    V --> SUB[karaoke subtitles]
+    V --> I[image chain]
+    SUB --> R[FFmpeg render + verify]
+    I --> R
+    R --> O[output/*.mp4 + metadata] --> U[YouTube upload]
+```
+
+## Your facts
+
+```json
+{
+  "topics": [
+    {
+      "id": "venus_day",
+      "angle": "a day on Venus is longer than its year",
+      "facts": [
+        "Venus takes about 243 Earth days to spin once on its axis.",
+        "Venus takes about 225 Earth days to orbit the Sun."
+      ],
+      "sources": ["https://science.nasa.gov/venus/venus-facts/"],
+      "hashtags": ["#venus"],
+      "weight": 2
+    }
+  ]
+}
+```
+
+Prefix unconfirmed news with `RUMOR:` and the script will be forced to say so. Put topic ids in
+`queue.txt` to choose what goes out next; otherwise the least used topic is picked (`weight` > 1 = more often).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `factreel init DIR --lang es` | new channel folder from a template |
+| `factreel make [-t TOPIC] [-n 3]` | generate videos into `output/` |
+| `factreel make --offline --voice dummy` | instant preview: no AI, silent voice, offline images |
+| `factreel topics` | topics and how many times each was used |
+| `factreel doctor [--voices --log]` | check everything; `--log` is perfect for a scheduled task |
+| `factreel upload [--privacy unlisted]` | upload pending videos to YouTube (`pip install "factreel[youtube]"`) |
+| `factreel run` | make + upload, for a daily scheduled task |
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md): every `channel.toml` option
+- [Providers](docs/providers.md): voices, images, LLMs and how to add your own
+- [YouTube upload](docs/youtube.md): OAuth setup in 5 minutes
+- [Scheduling](docs/scheduling.md): Windows Task Scheduler, cron, GitHub Actions
+
+## Responsible use
+
+FactReel declares AI-generated media when uploading, never invents facts on its own, and labels rumours.
+Please keep it that way: cite your sources, respect trademarks and music licences, and don't use it to
+mass-produce misleading content. Platforms penalise low-effort spam; good facts make good videos.
+
+## Contributing
+
+Contributions are very welcome, especially new languages, voice/image providers and platform uploaders.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md) for good first issues.
+
+## License
+
+[MIT](LICENSE) © Jorge Lamelas

factreel-0.1.0/README.es.md

@@ -0,0 +1,120 @@
+<div align="center">
+
+# FactReel 🎬✅
+
+**Vídeos cortos sin cara, con datos verificados y en piloto automático.**
+YouTube Shorts · TikTok · Reels a partir de una lista de hechos verificados, con servicios de IA gratuitos y un plan B para todo.
+
+[![CI](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/factreel.svg)](https://pypi.org/project/factreel/)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-green.svg)](LICENSE)
+
+[English](README.md) · [Español](README.es.md)
+
+<img src="docs/demo.gif" width="260" alt="Demo de FactReel: vídeo vertical con subtítulos palabra a palabra">
+
+</div>
+
+---
+
+La mayoría de los generadores de Shorts con IA dejan que el modelo se invente cosas. **FactReel no.** Tú
+escribes los hechos (con sus fuentes) una vez; la IA solo los convierte en un guion con gancho, y cada guion
+pasa por controles que rechazan cifras inventadas, ideas repetidas, rumores sin avisar y cualquier cosa que
+una segunda pasada de verificación no encuentre en tus hechos. Después lo narra, genera las imágenes, pone
+subtítulos tipo karaoke y renderiza un MP4 vertical listo para subir.
+
+Nace de un canal real que publica un Short cada día sin intervención, así que está hecho para **no pararse
+nunca por un mal día**: si se cae la voz, la API de imágenes o la IA del guion, entra la siguiente opción.
+
+## Qué incluye
+
+- 🛡️ **Guionista con controles anti-invenciones**: lista blanca de cifras, detección de repeticiones,
+  rumores etiquetados, verificación a temperatura 0 y un guion de reserva solo con los hechos, siempre correcto.
+- 🗣️ **Cadena de voces**: voces neuronales de Microsoft Edge (gratis, sin clave) → ElevenLabs → Cloudflare
+  Aura → la voz sin conexión de tu sistema. `factreel doctor` te avisa cuando un servicio cae y cuando vuelve.
+- 🖼️ **Cadena de imágenes**: FLUX en Cloudflare Workers AI → FLUX en NVIDIA NIM → tu propio generador
+  (GPU local, ComfyUI…) → archivo de imágenes anteriores → fondo procedural que siempre funciona sin internet.
+- 💬 **Subtítulos palabra a palabra** con la palabra que suena resaltada, sincronizados con la voz o con Whisper.
+- 🎞️ **Zoom Ken Burns suave y sin temblor** (render subpíxel), fundidos entre escenas, voz normalizada a
+  -14 LUFS y música de fondo opcional con créditos automáticos.
+- 🌍 **Español e inglés de serie** (prompts, meses, cuentas atrás). Otro idioma = un diccionario más.
+- 💸 **Gratis por defecto**: funciona sin ninguna clave; todo lo de pago es opcional y con tope de gasto.
+- 🔌 **Cualquier LLM compatible con OpenAI**: NVIDIA NIM, OpenRouter, Groq, OpenAI, Ollama, LM Studio, OmniRoute…
+- 📤 **Subida a YouTube opcional** marcando el contenido como "alterado o sintético", como exige YouTube.
+- ✅ **Comprueba cada vídeo** (resolución, audio, sin pantalla negra) antes de dejarlo en la cola de subida.
+
+## Empezar
+
+Necesitas **Python 3.10+** y **[FFmpeg](https://ffmpeg.org/download.html)** en el PATH.
+
+```bash
+pip install factreel
+factreel init mi-canal --lang es
+cd mi-canal
+factreel doctor        # comprueba FFmpeg, claves y cada voz
+factreel make          # -> output/20261020_180000_dia_venus.mp4 (+ metadatos .json/.txt)
+```
+
+Sin ninguna clave ya sale un vídeo con la voz gratuita de Edge, los hechos leídos tal cual y fondos sin
+conexión. Añade claves gratuitas en `.env` para tener guion e imágenes con IA:
+
+| Clave | Qué activa | Coste |
+| --- | --- | --- |
+| `NVIDIA_API_KEY` ([build.nvidia.com](https://build.nvidia.com)) | guion con IA + verificación, imágenes FLUX | créditos gratis |
+| `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN` | imágenes FLUX, voz de reserva, tiempos exactos de subtítulos (Whisper) | 10.000 neurons gratis al día, con tope |
+| `ELEVENLABS_API_KEY` | voz premium | opcional |
+
+## Tus hechos
+
+```json
+{
+  "topics": [
+    {
+      "id": "dia_venus",
+      "angle": "en Venus un día dura más que un año",
+      "facts": [
+        "Venus tarda unos 243 días terrestres en dar una vuelta sobre sí mismo.",
+        "Venus tarda unos 225 días terrestres en dar una vuelta al Sol."
+      ],
+      "sources": ["https://science.nasa.gov/venus/venus-facts/"],
+      "hashtags": ["#venus"],
+      "weight": 2
+    }
+  ]
+}
+```
+
+Empieza por `RUMOR:` las noticias sin confirmar y el guion tendrá que decirlo. Pon ids de temas en
+`queue.txt` para elegir qué sale después; si no, se elige el tema menos usado (`weight` > 1 = más a menudo).
+
+## Comandos
+
+| Comando | Qué hace |
+| --- | --- |
+| `factreel init CARPETA --lang es` | crea un canal desde una plantilla |
+| `factreel make [-t TEMA] [-n 3]` | genera vídeos en `output/` |
+| `factreel make --offline --voice dummy` | vista previa al instante: sin IA, voz muda, imágenes sin conexión |
+| `factreel topics` | temas y cuántas veces se ha usado cada uno |
+| `factreel doctor [--voices --log]` | lo comprueba todo; `--log` es ideal para una tarea programada |
+| `factreel upload [--privacy unlisted]` | sube los vídeos pendientes a YouTube (`pip install "factreel[youtube]"`) |
+| `factreel run` | genera y sube, para la tarea programada diaria |
+
+## Documentación
+
+- [Configuración](docs/configuration.md) · [Proveedores](docs/providers.md) · [Subida a YouTube](docs/youtube.md) · [Programar tareas](docs/scheduling.md) (en inglés)
+
+## Uso responsable
+
+FactReel declara el contenido generado con IA al subirlo, no se inventa datos y etiqueta los rumores.
+Mantenlo así: cita tus fuentes, respeta marcas y licencias de música y no lo uses para producir en masa
+contenido engañoso. Las plataformas penalizan el spam; buenos datos hacen buenos vídeos.
+
+## Contribuir
+
+¡Las contribuciones son muy bienvenidas!, sobre todo idiomas nuevos, proveedores de voz e imagen y
+subidas a otras plataformas. Mira [CONTRIBUTING.md](CONTRIBUTING.md) y la [hoja de ruta](ROADMAP.md).
+Puedes escribir las issues y los PR en español o en inglés.
+
+## Licencia
+
+[MIT](LICENSE) © Jorge Lamelas

factreel-0.1.0/README.md

@@ -0,0 +1,142 @@
+<div align="center">
+
+# FactReel 🎬✅
+
+**Fact-checked faceless short videos, on autopilot.**
+YouTube Shorts · TikTok · Reels, from a list of verified facts, with free AI services and a fallback for everything.
+
+[![CI](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadY2J/factreel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/factreel.svg)](https://pypi.org/project/factreel/)
+[![Python](https://img.shields.io/pypi/pyversions/factreel.svg)](https://pypi.org/project/factreel/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[English](README.md) · [Español](README.es.md)
+
+<img src="docs/demo.gif" width="260" alt="FactReel demo: vertical video with word-by-word subtitles">
+
+</div>
+
+---
+
+Most "AI shorts generators" let a language model make things up. **FactReel doesn't.** You write the facts
+(with sources) once; the AI only turns them into a punchy script, and every script goes through guards that
+reject invented numbers, repeated ideas, unlabelled rumours and anything a second fact-checking pass can't
+find in your facts. Then it narrates it, draws the images, burns karaoke subtitles and renders a vertical
+MP4 ready to upload.
+
+It grew out of a real channel that publishes a Short every day unattended, so it is built to **never stop
+on a bad day**: if the voice service, the image API or the script AI is down, the next option in the chain
+takes over.
+
+## Features
+
+- 🛡️ **Anti-hallucination script writer**: number whitelist, repetition check, rumour labelling, a
+  temperature-0 fact-check pass, and a facts-only fallback that is always correct.
+- 🗣️ **Voice fallback chain**: Microsoft Edge neural voices (free, no key) → ElevenLabs → Cloudflare
+  Aura → your OS's offline voice. `factreel doctor` tells you when a service is down and when it is back.
+- 🖼️ **Image fallback chain**: Cloudflare Workers AI FLUX → NVIDIA NIM FLUX → your own generator
+  (local GPU, ComfyUI…) → archive of previous images → procedural background that always works offline.
+- 💬 **Word-by-word subtitles** with the spoken word highlighted, synced from the TTS engine or Whisper.
+- 🎞️ **Smooth Ken Burns zoom without jitter** (sub-pixel rendering), cross-fades on scene changes,
+  voice normalised to -14 LUFS, optional background music with automatic credits.
+- 🌍 **Spanish and English first-class** (prompts, month names, countdowns). More languages = one dict.
+- 💸 **Free by default**: runs with zero API keys; every paid service is optional and budget-capped.
+- 🔌 **Any OpenAI-compatible LLM**: NVIDIA NIM, OpenRouter, Groq, OpenAI, Ollama, LM Studio, OmniRoute…
+- 📤 **Optional YouTube upload** with the "altered or synthetic content" flag set for you.
+- ✅ **Verifies every render** (resolution, audio, no black screen) before it reaches the upload queue.
+
+## Quick start
+
+You need **Python 3.10+** and **[FFmpeg](https://ffmpeg.org/download.html)** on your PATH.
+
+```bash
+pip install factreel
+factreel init my-channel --lang en      # or --lang es
+cd my-channel
+factreel doctor                         # checks FFmpeg, keys and every voice
+factreel make                           # -> output/20261020_180000_venus_day.mp4 (+ .json/.txt metadata)
+```
+
+That's it: with no keys at all you get a video with the free Edge voice, the facts read as they are and
+offline backgrounds. Add free keys to `.env` to unlock the AI script and AI images:
+
+| Key | What it unlocks | Cost |
+| --- | --- | --- |
+| `NVIDIA_API_KEY` ([build.nvidia.com](https://build.nvidia.com)) | AI script + fact check, FLUX images | free credits |
+| `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN` | FLUX images, backup voice, exact subtitle timing (Whisper) | 10,000 free neurons/day, capped |
+| `ELEVENLABS_API_KEY` | premium voice | optional |
+
+## How it works
+
+```mermaid
+flowchart LR
+    F[facts.json<br/>verified facts + sources] --> T[topic rotation<br/>queue.txt / least used]
+    T --> S[AI script]
+    S --> G{guards<br/>numbers · repeats<br/>rumours · fact check}
+    G -- rejected --> S
+    G -- gives up --> FB[facts-only script]
+    G -- ok --> V[voice chain]
+    FB --> V
+    V --> SUB[karaoke subtitles]
+    V --> I[image chain]
+    SUB --> R[FFmpeg render + verify]
+    I --> R
+    R --> O[output/*.mp4 + metadata] --> U[YouTube upload]
+```
+
+## Your facts
+
+```json
+{
+  "topics": [
+    {
+      "id": "venus_day",
+      "angle": "a day on Venus is longer than its year",
+      "facts": [
+        "Venus takes about 243 Earth days to spin once on its axis.",
+        "Venus takes about 225 Earth days to orbit the Sun."
+      ],
+      "sources": ["https://science.nasa.gov/venus/venus-facts/"],
+      "hashtags": ["#venus"],
+      "weight": 2
+    }
+  ]
+}
+```
+
+Prefix unconfirmed news with `RUMOR:` and the script will be forced to say so. Put topic ids in
+`queue.txt` to choose what goes out next; otherwise the least used topic is picked (`weight` > 1 = more often).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `factreel init DIR --lang es` | new channel folder from a template |
+| `factreel make [-t TOPIC] [-n 3]` | generate videos into `output/` |
+| `factreel make --offline --voice dummy` | instant preview: no AI, silent voice, offline images |
+| `factreel topics` | topics and how many times each was used |
+| `factreel doctor [--voices --log]` | check everything; `--log` is perfect for a scheduled task |
+| `factreel upload [--privacy unlisted]` | upload pending videos to YouTube (`pip install "factreel[youtube]"`) |
+| `factreel run` | make + upload, for a daily scheduled task |
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md): every `channel.toml` option
+- [Providers](docs/providers.md): voices, images, LLMs and how to add your own
+- [YouTube upload](docs/youtube.md): OAuth setup in 5 minutes
+- [Scheduling](docs/scheduling.md): Windows Task Scheduler, cron, GitHub Actions
+
+## Responsible use
+
+FactReel declares AI-generated media when uploading, never invents facts on its own, and labels rumours.
+Please keep it that way: cite your sources, respect trademarks and music licences, and don't use it to
+mass-produce misleading content. Platforms penalise low-effort spam; good facts make good videos.
+
+## Contributing
+
+Contributions are very welcome, especially new languages, voice/image providers and platform uploaders.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md) for good first issues.
+
+## License
+
+[MIT](LICENSE) © Jorge Lamelas