Instalación

En resumen

Si ya tienes Python 3.14 y uv:

1. Descarga el paquete de tu sistema desde la última release.
2. Extráelo y pon la carpeta de los ejecutables en el PATH (Windows o Ubuntu).
3. Abre una terminal nueva y crea un proyecto:

gaanim init video mi-video   # crea el proyecto y su entorno con uv
gaanim mi-video              # abre la vista previa

Si algo falla, ve a Solución de problemas. El resto de la página explica cada paso con detalle.

Requisitos

• Python ejecuta tus escenas. Instálalo desde python.org, con winget install Python.Python.3.14 (Windows) o, en cualquier sistema, con uv python install 3.14. En Ubuntu tiene que ser 3.14 porque el motor enlaza libpython3.14.so.
• uv crea el entorno de cada proyecto.
• FFmpeg solo hace falta para exportar video (MP4, WebM, MOV, WebP animado y GIF) y para scene.media.video(). Sin él tienes la vista previa completa y puedes exportar secuencias PNG.

macOS todavía no tiene paquete. Para compilar Gaanim desde el código, sigue el README del repositorio.

Descarga

Cada versión se publica en las releases de GitHub con un paquete por sistema y su suma SHA-256. No necesitas Rust ni compilar nada.

• gaanim es el único ejecutable: inicio, vista previa, presentaciones, reproductor de paquetes .gaanim y línea de comandos.
• Lo acompañan tres bibliotecas: el motor (gaanim_engine), el soporte de Python (gaanim_python_plugin), que gaanim carga solo al abrir una escena o un proyecto, y la biblioteca estándar de Rust (std-…). Deja siempre todos los archivos del paquete en la misma carpeta.
• El wheel gaanim-<versión>-py3-none-any.whl es el paquete de autoría: tipos, stubs y ayudas para que tu editor autocomplete la API. No contiene el renderer, así que python main.py falla a propósito: las escenas siempre se ejecutan con gaanim.

Verifica la descarga

Descarga también el archivo .sha256 de tu paquete y compara las sumas:

# Windows (PowerShell): los dos valores deben coincidir
Get-FileHash .\gaanim-v*-windows-x64.zip -Algorithm SHA256
Get-Content .\gaanim-v*-windows-x64.zip.sha256

# Ubuntu: imprime "OK" si coincide
sha256sum -c gaanim-v*-linux-x64.tar.gz.sha256

Instala en Windows

1. Extrae el zip en una carpeta, por ejemplo C:\Tools\gaanim. El wheel debe quedar junto a gaanim.exe: ahí lo busca.
2. Añade esa carpeta al PATH de tu usuario, desde Configuración → Variables de entorno → Path, o con PowerShell:

Expand-Archive .\gaanim-v*-windows-x64.zip -DestinationPath C:\Tools\gaanim
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;C:\Tools\gaanim", "User")

3. Abre una terminal nueva para que tome el PATH actualizado.
4. Opcional: gaanim register abre los archivos .gaanim con doble clic y muestra su portada en el Explorador (ver Compartir sin Python).

gaanim.exe arranca aunque Python no esté en el PATH: solo lo busca cuando abres una escena o un proyecto.

Instala en Ubuntu

Extrae el paquete en ~/.local/lib/gaanim, con el wheel junto al ejecutable, donde gaanim lo busca, y enlaza el ejecutable desde ~/.local/bin:

mkdir -p ~/.local/lib/gaanim ~/.local/bin
tar -xzf gaanim-v*-linux-x64.tar.gz -C ~/.local/lib/gaanim
ln -sf ~/.local/lib/gaanim/gaanim ~/.local/bin/gaanim
~/.local/bin/gaanim register   # opcional: doble clic y portadas de los .gaanim

Ubuntu añade ~/.local/bin al PATH si la carpeta existe al iniciar sesión. Si acabas de crearla y gaanim no aparece, cierra la sesión y vuelve a entrar.

Comprueba la instalación

gaanim --version   # imprime la versión instalada
gaanim --help      # lista los comandos

Ninguno de los dos necesita Python. Si funcionan, los ejecutables están bien instalados; el siguiente paso comprueba Python y uv.

Crea un proyecto

gaanim init video mi-video      # video 16:9
gaanim init slides mi-charla    # presentación con pasos
gaanim init video .             # en la carpeta actual

init genera la estructura del proyecto y, con uv, un entorno .venv con Python 3.14 y el wheel de autoría:

mi-video/
  gaanim.toml       # nombre, tipo, archivo de entrada y carpetas
  main.py           # escena de ejemplo: edítala
  assets/           # imágenes, SVG, fuentes, audio
  exports/          # destino sugerido para las exportaciones
  pyproject.toml    # proyecto uv con Python 3.14
  .python-version
  README.md
  AGENTS.md         # instrucciones para asistentes de código
  .gitignore
  .venv/            # entorno creado con uv

Si la carpeta ya contiene archivos del proyecto, init se detiene para no pisarlos. Con --force reescribe esos archivos (incluido main.py) sin tocar tus assets.

También puedes crear y abrir proyectos sin terminal: gaanim sin argumentos abre el Inicio, con los proyectos recientes y un diagnóstico de Python y uv.

Usa el proyecto

Estos son los comandos del día a día. La primera animación los usa paso a paso.

gaanim mi-video                                     # vista previa; guardar recarga
gaanim check mi-video                               # ejecuta la escena sin ventana
gaanim check mi-video --strict                      # falla también con avisos
gaanim export mi-video --output mi-video/exports/demo.mp4
gaanim --present --monitor 1 mi-charla              # presenta en el monitor 1

Dentro de la carpeta del proyecto, gaanim . abre su archivo de entrada. También puedes abrir un script suelto con gaanim escena.py.

Tu editor autocompleta la API si usa el intérprete de mi-video/.venv.

Cómo encuentra Python

No hace falta activar el entorno. Al abrir una escena, gaanim usa el primer intérprete que encuentra:

1. El entorno activo (VIRTUAL_ENV).
2. Una carpeta .venv, venv o env junto al proyecto o al directorio actual, subiendo hasta cuatro niveles.
3. El Python del sistema: py -3.14, python o python3 en Windows; python3.14, python3 o python en Ubuntu.
4. El Python 3.14 que haya instalado uv.

Los pasos 1 y 2 no siguen buscando si encuentran otra versión: un entorno con Python 3.12 produce un error aunque tengas 3.14 instalado.

Actualiza

Cuando sale una versión nueva, la pantalla de inicio lo avisa: What’s new abre su página y Update la instala sobre la carpeta de Gaanim; al terminar, Restart abre la versión nueva. Desde la terminal hace lo mismo:

gaanim update --check   # solo dice si hay una versión nueva
gaanim update           # la descarga y la instala

Gaanim descarga el paquete de tu sistema, comprueba su suma SHA-256, lo descomprime junto a la instalación, verifica que arranca y solo entonces reemplaza los archivos; si algo falla, deja los anteriores. Ver gaanim update.

A mano también se puede: descarga la release nueva y reemplaza todos los archivos de la carpeta, porque el ejecutable y sus bibliotecas deben venir de la misma versión. En ningún caso hace falta recrear los proyectos: al abrir uno, Gaanim reinstala su paquete de autoría si no coincide con la versión del ejecutable.

Solución de problemas

• Python >=3.14 was not found o Python 3.14 was not found: instala Python 3.14 (uv python install 3.14) y vuelve a intentarlo.
• Gaanim requires Python … but found Python 3.x: el entorno activo o el .venv del proyecto usa otra versión. Desactívalo, o recrea el entorno con uv venv --python 3.14.
• gaanim_engine.dll o std-….dll no encontrado, o salida -1073741515 (Windows): faltan archivos del paquete junto a gaanim.exe. Extrae de nuevo el zip completo en la misma carpeta.
• … belongs to another build of Gaanim o could not load
…gaanim_python_plugin…: los archivos de la carpeta son de versiones distintas. Reemplázalos todos con los de una misma release.
• authoring environment not ready: falta uv, o el wheel no está junto a gaanim (en Ubuntu, en ~/.local/lib/gaanim). La vista previa funciona igual, pero el editor no autocompleta.
• gaanim check: could not load project: revisa que entry en gaanim.toml sea una ruta relativa a un archivo que exista.
• La exportación dice que ffmpeg no está en el PATH (was not found on
PATH): instala FFmpeg y añádelo al PATH, o exporta una secuencia PNG (--output frames/frame.png).