algan 0.0.0__tar.gz

algan-0.0.0/.gitignore

@@ -0,0 +1,210 @@
+# Algan videos
+# Heavy render baselines are release assets. Local rebaselines remain
+# discoverable by scripts/package_baselines.py but must not be recommitted.
+tests/full_renders/expected_outputs_*/
+tests/path_traced/expected_outputs_*/
+**/output_errors/
+benchmarks/_*_out/
+**/algan_outputs/
+# tests/full_renders writes its renders next to the baselines, in a directory
+# the glob above just misses (test_full_renders.OUTPUT_DIR).
+**/algan_outputs2/
+algan_outputs/
+algan_outputs
+algan_cache
+
+# What benchmarks/_mps_capability_probe.py writes. It is a measurement of the
+# machine it ran on, so it belongs in a CI artifact, not in the tree.
+mps_probe_results.json
+probe-output.txt
+
+# Same for benchmarks/_mps_vs_cpu_torch_speed.py.
+benchmarks/mps_vs_cpu_speed.json
+speed-output.txt
+
+# The frame benchmarks/_mps_render_smoke.py draws. It is what the run produced
+# on the machine it ran on -- a CI artifact, not a baseline: nothing compares
+# against it, and the two devices legitimately tessellate differently.
+mps_render_smoke/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+.agents
+# Ignore personal Claude Code state, but track the shared project config: the
+# SessionStart hook is what makes Claude Code on the web able to build and test
+# this repo, so it has to be committed. Git will not look inside an ignored
+# directory, hence ignoring the contents rather than the directory itself.
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+.codex
+.devcontainer
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+*.log
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+docs/source/_autosummary/
+docs/source/reference/
+docs/source/_build/
+docs/rendering_times.csv
+#i18n ####
+docs/i18n/gettext/.doctrees
+docs/i18n/**/*.mo
+docs/i18n/translatable.po
+docs/i18n/untranslatable.po
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+jupyter/
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# PyCharm
+/.idea/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+*.pyc
+*.bak
+.DS_Store
+
+.floo
+.flooignore
+.vscode
+.vs
+*.xml
+*.iml
+media
+**/media/
+.eggs/
+build/
+dist/
+
+/media_dir.txt
+# ^TODO: Remove the need for this with a proper config file
+
+# Ignore the built dependencies
+third_party/*
+
+/debug/
+/tests/output_errors/
+/scratch/
+/tests/full_renders/output_errors/
+
+# Session scratch (briefs for subagents, interim measurements)
+/scratch_*
+
+# The renderer audit's Three.js back end (benchmarks/renderer_audit/three_render.mjs)
+# needs three + three-gpu-pathtracer + playwright installed beside it; the
+# script's header says how. Reference renders are regenerated, not committed.
+benchmarks/renderer_audit/node_modules/
+benchmarks/renderer_audit/package.json
+benchmarks/renderer_audit/package-lock.json
+
+# What benchmarks/_mps_torch_op_probe.py writes in CI, for the artifact and
+# for the end-of-job replay. A measurement of the machine it ran on.
+torch-op-probe.txt
+pytest-output.txt
+compile-trace.txt
+
+# Written by algan/utils/profiling_utils.py into the working directory
+algan_profile_report*.txt
+
+# The patched Quadrants wheels `scripts/build_quadrants_wheels.py` downloads.
+# 20-30 MiB each and a full matrix is twelve of them, so the bytes stay out of
+# git for the reason the render baselines do (`tests/README.md`, "Where the
+# heavy baselines live"). The manifest beside them IS committed: it carries the
+# run id, the commit and a sha256 per wheel and per patch, so which wheel a
+# measurement was taken on stays recoverable without the wheel being here.
+/quadrants_wheels/*
+!/quadrants_wheels/manifest.json

algan-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Algorithmic Simplicity
+
+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.

algan-0.0.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.5
+Name: algan
+Version: 0.0.0
+Summary: The simplest animation engine for 3D graphics.
+Project-URL: repository, https://github.com/algorithmicsimplicity/algan
+Project-URL: documentation, https://algorithmicsimplicity.github.io/algan
+Project-URL: homepage, https://github.com/algorithmicsimplicity/algan
+Project-URL: Bug Tracker, https://github.com/algorithmicsimplicity/algan/issues
+Project-URL: X / Twitter, https://x.com/algorithmicsimplicity
+Project-URL: Discord, https://discord.gg/NvarFmvXKm
+Author-email: Algorithmic Simplicity <algorithmicsimplicity@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: algan/external_libraries/ground/LICENSE
+License-File: algan/external_libraries/manim/LICENSE
+License-File: algan/external_libraries/manim/LICENSE.community
+License-File: algan/external_libraries/sect/LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.14,>=3.10
+Requires-Dist: algan-quadrants==1.3.0.post2
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: decision>=0.3.0
+Requires-Dist: decorator>=4.3.2
+Requires-Dist: dendroid>=1.6.0
+Requires-Dist: isosurfaces>=0.1.0
+Requires-Dist: manimpango>=0.5.0; sys_platform != 'linux'
+Requires-Dist: mapbox-earcut>=1.0.0
+Requires-Dist: moviepy>=2.2.0
+Requires-Dist: networkx>=2.6
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pillow>=9.0
+Requires-Dist: prioq>=0.6.0
+Requires-Dist: psutil>=6.1.1
+Requires-Dist: pygltflib>=1.16
+Requires-Dist: pygments>=2.0.0
+Requires-Dist: pyttsx3>=2.0
+Requires-Dist: reprit>=0.9.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: setuptools>=61
+Requires-Dist: skia-pathops>=0.7.0
+Requires-Dist: svgelements>=1.0.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: tqdm>=4.51.0
+Requires-Dist: trimesh>=4.0.0
+Requires-Dist: typing-extensions>=4.12.0
+Provides-Extra: audio
+Requires-Dist: torchaudio>=2.0.0; extra == 'audio'
+Requires-Dist: transformers>=4.30.0; extra == 'audio'
+Provides-Extra: dev
+Requires-Dist: furo>=2024.8.6; extra == 'dev'
+Requires-Dist: gitpython>=3.1.44; extra == 'dev'
+Requires-Dist: matplotlib>=3.9.4; extra == 'dev'
+Requires-Dist: myst-parser>=3.0.1; extra == 'dev'
+Requires-Dist: opencv-python-headless<5,>=4.5; extra == 'dev'
+Requires-Dist: parameterized>=0.9.0; extra == 'dev'
+Requires-Dist: pyassimp>=5.0; extra == 'dev'
+Requires-Dist: pygithub>=2.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist<3.0,>=2.2; extra == 'dev'
+Requires-Dist: requests>=2.32.3; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'dev'
+Requires-Dist: sphinx-design>=0.6.1; extra == 'dev'
+Requires-Dist: sphinx-reredirects>=0.1.5; extra == 'dev'
+Requires-Dist: sphinx>=7.4.7; extra == 'dev'
+Requires-Dist: sphinxcontrib-programoutput>=0.18; extra == 'dev'
+Requires-Dist: sphinxext-opengraph>=0.9.1; extra == 'dev'
+Requires-Dist: taichi>=1.7.4; extra == 'dev'
+Requires-Dist: torchaudio>=2.0.0; extra == 'dev'
+Requires-Dist: transformers>=4.30.0; extra == 'dev'
+Requires-Dist: types-decorator>=5.1.8.20250121; extra == 'dev'
+Requires-Dist: types-pillow>=10.2.0.20240822; extra == 'dev'
+Requires-Dist: types-pygments>=2.19.0.20250107; extra == 'dev'
+Provides-Extra: fbx
+Requires-Dist: pyassimp>=5.0; extra == 'fbx'
+Provides-Extra: pango
+Requires-Dist: manimpango>=0.5.0; extra == 'pango'
+Provides-Extra: taichi
+Requires-Dist: taichi>=1.7.4; extra == 'taichi'
+Description-Content-Type: text/markdown
+
+# Algan
+
+<p align="center">
+  <strong>Full-featured 2D/3D programmatic animation engine for explanatory mathematics and technical videos.</strong>
+</p>
+
+<p align="center">
+  <a href="https://algorithmicsimplicity.github.io/algan"><img src="https://img.shields.io/badge/docs-algorithmicsimplicity.github.io%2Falgan-blue.svg" alt="Documentation" /></a>
+  <a href="https://pypi.org/project/algan/"><img src="https://img.shields.io/pypi/v/algan.svg" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/algan/"><img src="https://img.shields.io/pypi/pyversions/algan.svg" alt="Python versions" /></a>
+  <a href="https://discord.gg/NvarFmvXKm"><img src="https://img.shields.io/badge/Discord-chat-7289da.svg?logo=discord&logoColor=white" alt="Discord Community" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
+</p>
+
+---
+
+Algan is designed to be a successor to Manim with full-featured 3-D raytracing capabilities.
+
+As seen on [AlgorithmicSimplicity](https://www.youtube.com/@algorithmicsimplicity).
+
+---
+
+## Key Features
+
+- **Manim Feature Parity**: Everything you know and love from Manim.
+- **GPU Ray Tracing**: High-fidelity optical effects including depth of field, area lights, glossy reflections, refractive glass, and soft shadows.
+- **Declarative Timeline Contexts**: Intuitive animation staging with `Seq()`, `Sync()`, `Lag()`, `Off()`, and `Speech()` blocks makes animation code modular and re-usable.
+- **Unified 2D/3D Geometry**: Seamless morphing and interpolation between 2D Bézier circuits and 3D meshes with `become()`.
+- **Audio & Speech Alignment**: Automatic word-level forced alignment to synchronize on-screen animations with narration.
+
+---
+
+## Installation
+
+```bash
+pip install algan
+```
+
+Every dependency ships wheels, so there is nothing to build and no system
+package to install first. The installed footprint is large (~5 GB on Linux,
+mostly the CUDA build of `torch` and its NVIDIA dependencies).
+
+### Optional: Pango text on Linux
+
+`Text` typesets with your system fonts through Pango, which is installed with
+Algan on Windows and macOS. `manimpango` publishes no Linux wheel, so on Linux
+it is an extra instead — without it `Text` falls back to LaTeX's text mode, and
+Manim's `MarkupText` and `Paragraph` are absent. Installing it builds Pango
+from source and wants its headers first:
+
+```bash
+sudo apt-get install -y build-essential python3-dev libpango1.0-dev pkg-config
+pip install "algan[pango]"
+```
+
+For per-OS instructions (GPU acceleration, optional LaTeX for formulas, speech), see the [Installation Guide](https://algorithmicsimplicity.github.io/algan/installation.html).
+
+---
+
+## Quickstart
+
+Save this script as `scene.py`:
+
+```python
+from algan import *
+
+# 1. Make 3-D objects with physical materials
+sphere = Sphere(color=BLUE, radius=1.2)
+sphere.set_material(
+    MeshPhysicalMaterial(
+        roughness=0.15,
+        metalness=0.1,
+        clearcoat=1.0,
+        clearcoat_roughness=0.08,
+    )
+)
+
+# 2. Define animation timeline with contexts
+sphere.spawn()
+with Sync(runtime=2):
+    sphere.move(RIGHT * 2)
+    sphere.rotate(180, OUT, about=ORIGIN)
+    sphere.color = RED
+
+# 3. Render video
+Scene.save_video("quickstart.mp4")
+```
+
+Run with Python or the Algan CLI:
+
+```bash
+# Using python
+python scene.py
+
+# Using the algan CLI
+algan render scene.py
+```
+
+The output video will be written to `algan_outputs/quickstart.mp4`.
+
+---
+
+## Command Line Interface (CLI)
+
+Algan includes a first-class CLI:
+
+```bash
+algan check                 # Verify PyTorch, GPU acceleration, the kernel compiler, FFmpeg, LaTeX & paths
+algan new my_scene.py       # Scaffold a new scene script
+algan render my_scene.py    # Render scene to video
+```
+
+`render` takes `-q {preview,ld,md,hd,production,uhd}` for the video preset and
+`-o` for the directory or file to write to. Both fill in what the script leaves
+open: a `Scene.save_video("intro")` still decides the name, and a path with a
+directory in it still decides everything.
+
+```bash
+algan render my_scene.py -q hd -o renders/          # renders/intro.mp4, at HD
+algan render my_scene.py --no-daemon -- --seed 7    # fresh process, args forwarded
+```
+
+A scene script may have a command line of its own (such as a
+[`Project`](https://algorithmicsimplicity.github.io/algan/reference/algan.project.Project.html)
+calling `run_cli()`) so any argument this CLI does not recognise is
+forwarded to it, as is everything after `--`:
+
+```bash
+algan render project.py -q hd --render-video intro   # -q ours, --render-video the project's
+algan render project.py -- --help                    # the project's help, not ours
+```
+
+Where both name the same thing, the script wins: `-q` sets the default preset,
+and a `Project`'s own `--video-settings` (or its `video_settings=` argument)
+overrides it.
+
+### The warm render daemon
+
+The first render of a session pays several seconds of library import plus
+Taichi kernel preparation. Algan pays that once: the first `python scene.py`
+starts a background daemon, and every later run hands its script to that warm
+process and starts rendering in about a second. Nothing is launched
+differently — it happens inside `import algan`.
+
+```bash
+algan daemon                # run one in this terminal (Enter re-renders, q quits)
+algan daemon ping           # is one running?
+algan daemon render         # re-render the last script (bind an editor key to it)
+algan daemon quit           # stop it (algan daemon --stop is the same)
+```
+
+Those verbs each carry the token from the daemon's state file
+(`$ALGAN_HOME/daemon.json`, default `~/.algan`), which is also where the port
+lives — the daemon prefers 46711 and falls back to an ephemeral port when it is
+taken.
+
+**A script served by the daemon runs in another process**, and three things
+follow from that:
+
+- everything above `import algan` runs **twice** — once in your process, once
+  in the daemon — so keep side effects below the import;
+- `atexit` handlers do not run, because the warm process never shuts down;
+- `stdin` is `/dev/null`, since the daemon's own stdin is its re-render trigger.
+
+Everything else is reproduced: `sys.argv`, the working directory, the full
+environment, stdout/stderr (including from ffmpeg and other subprocesses),
+their tty-ness, and the exit code. `ALGAN_USE_DAEMON=0` runs in-process,
+`ALGAN_AUTO_DAEMON=0` only stops new ones being started, and a script being
+debugged is never handed off.
+
+---
+
+## Documentation
+
+- **Documentation**: [https://algorithmicsimplicity.github.io/algan](https://algorithmicsimplicity.github.io/algan)
+- **Tutorials**: [New User Tutorials](https://algorithmicsimplicity.github.io/algan/new_user_tutorials/index.html)
+- **Discord Community**: [Join our Discord](https://discord.gg/NvarFmvXKm)
+- **Issue Tracker**: [GitHub Issues](https://github.com/algorithmicsimplicity/algan/issues)
+
+---
+
+## License
+
+Algan is licensed under the MIT License (see [LICENSE](LICENSE)). Copyright &copy; Algorithmic Simplicity.

algan-0.0.0/README.md

@@ -0,0 +1,184 @@
+# Algan
+
+<p align="center">
+  <strong>Full-featured 2D/3D programmatic animation engine for explanatory mathematics and technical videos.</strong>
+</p>
+
+<p align="center">
+  <a href="https://algorithmicsimplicity.github.io/algan"><img src="https://img.shields.io/badge/docs-algorithmicsimplicity.github.io%2Falgan-blue.svg" alt="Documentation" /></a>
+  <a href="https://pypi.org/project/algan/"><img src="https://img.shields.io/pypi/v/algan.svg" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/algan/"><img src="https://img.shields.io/pypi/pyversions/algan.svg" alt="Python versions" /></a>
+  <a href="https://discord.gg/NvarFmvXKm"><img src="https://img.shields.io/badge/Discord-chat-7289da.svg?logo=discord&logoColor=white" alt="Discord Community" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
+</p>
+
+---
+
+Algan is designed to be a successor to Manim with full-featured 3-D raytracing capabilities.
+
+As seen on [AlgorithmicSimplicity](https://www.youtube.com/@algorithmicsimplicity).
+
+---
+
+## Key Features
+
+- **Manim Feature Parity**: Everything you know and love from Manim.
+- **GPU Ray Tracing**: High-fidelity optical effects including depth of field, area lights, glossy reflections, refractive glass, and soft shadows.
+- **Declarative Timeline Contexts**: Intuitive animation staging with `Seq()`, `Sync()`, `Lag()`, `Off()`, and `Speech()` blocks makes animation code modular and re-usable.
+- **Unified 2D/3D Geometry**: Seamless morphing and interpolation between 2D Bézier circuits and 3D meshes with `become()`.
+- **Audio & Speech Alignment**: Automatic word-level forced alignment to synchronize on-screen animations with narration.
+
+---
+
+## Installation
+
+```bash
+pip install algan
+```
+
+Every dependency ships wheels, so there is nothing to build and no system
+package to install first. The installed footprint is large (~5 GB on Linux,
+mostly the CUDA build of `torch` and its NVIDIA dependencies).
+
+### Optional: Pango text on Linux
+
+`Text` typesets with your system fonts through Pango, which is installed with
+Algan on Windows and macOS. `manimpango` publishes no Linux wheel, so on Linux
+it is an extra instead — without it `Text` falls back to LaTeX's text mode, and
+Manim's `MarkupText` and `Paragraph` are absent. Installing it builds Pango
+from source and wants its headers first:
+
+```bash
+sudo apt-get install -y build-essential python3-dev libpango1.0-dev pkg-config
+pip install "algan[pango]"
+```
+
+For per-OS instructions (GPU acceleration, optional LaTeX for formulas, speech), see the [Installation Guide](https://algorithmicsimplicity.github.io/algan/installation.html).
+
+---
+
+## Quickstart
+
+Save this script as `scene.py`:
+
+```python
+from algan import *
+
+# 1. Make 3-D objects with physical materials
+sphere = Sphere(color=BLUE, radius=1.2)
+sphere.set_material(
+    MeshPhysicalMaterial(
+        roughness=0.15,
+        metalness=0.1,
+        clearcoat=1.0,
+        clearcoat_roughness=0.08,
+    )
+)
+
+# 2. Define animation timeline with contexts
+sphere.spawn()
+with Sync(runtime=2):
+    sphere.move(RIGHT * 2)
+    sphere.rotate(180, OUT, about=ORIGIN)
+    sphere.color = RED
+
+# 3. Render video
+Scene.save_video("quickstart.mp4")
+```
+
+Run with Python or the Algan CLI:
+
+```bash
+# Using python
+python scene.py
+
+# Using the algan CLI
+algan render scene.py
+```
+
+The output video will be written to `algan_outputs/quickstart.mp4`.
+
+---
+
+## Command Line Interface (CLI)
+
+Algan includes a first-class CLI:
+
+```bash
+algan check                 # Verify PyTorch, GPU acceleration, the kernel compiler, FFmpeg, LaTeX & paths
+algan new my_scene.py       # Scaffold a new scene script
+algan render my_scene.py    # Render scene to video
+```
+
+`render` takes `-q {preview,ld,md,hd,production,uhd}` for the video preset and
+`-o` for the directory or file to write to. Both fill in what the script leaves
+open: a `Scene.save_video("intro")` still decides the name, and a path with a
+directory in it still decides everything.
+
+```bash
+algan render my_scene.py -q hd -o renders/          # renders/intro.mp4, at HD
+algan render my_scene.py --no-daemon -- --seed 7    # fresh process, args forwarded
+```
+
+A scene script may have a command line of its own (such as a
+[`Project`](https://algorithmicsimplicity.github.io/algan/reference/algan.project.Project.html)
+calling `run_cli()`) so any argument this CLI does not recognise is
+forwarded to it, as is everything after `--`:
+
+```bash
+algan render project.py -q hd --render-video intro   # -q ours, --render-video the project's
+algan render project.py -- --help                    # the project's help, not ours
+```
+
+Where both name the same thing, the script wins: `-q` sets the default preset,
+and a `Project`'s own `--video-settings` (or its `video_settings=` argument)
+overrides it.
+
+### The warm render daemon
+
+The first render of a session pays several seconds of library import plus
+Taichi kernel preparation. Algan pays that once: the first `python scene.py`
+starts a background daemon, and every later run hands its script to that warm
+process and starts rendering in about a second. Nothing is launched
+differently — it happens inside `import algan`.
+
+```bash
+algan daemon                # run one in this terminal (Enter re-renders, q quits)
+algan daemon ping           # is one running?
+algan daemon render         # re-render the last script (bind an editor key to it)
+algan daemon quit           # stop it (algan daemon --stop is the same)
+```
+
+Those verbs each carry the token from the daemon's state file
+(`$ALGAN_HOME/daemon.json`, default `~/.algan`), which is also where the port
+lives — the daemon prefers 46711 and falls back to an ephemeral port when it is
+taken.
+
+**A script served by the daemon runs in another process**, and three things
+follow from that:
+
+- everything above `import algan` runs **twice** — once in your process, once
+  in the daemon — so keep side effects below the import;
+- `atexit` handlers do not run, because the warm process never shuts down;
+- `stdin` is `/dev/null`, since the daemon's own stdin is its re-render trigger.
+
+Everything else is reproduced: `sys.argv`, the working directory, the full
+environment, stdout/stderr (including from ffmpeg and other subprocesses),
+their tty-ness, and the exit code. `ALGAN_USE_DAEMON=0` runs in-process,
+`ALGAN_AUTO_DAEMON=0` only stops new ones being started, and a script being
+debugged is never handed off.
+
+---
+
+## Documentation
+
+- **Documentation**: [https://algorithmicsimplicity.github.io/algan](https://algorithmicsimplicity.github.io/algan)
+- **Tutorials**: [New User Tutorials](https://algorithmicsimplicity.github.io/algan/new_user_tutorials/index.html)
+- **Discord Community**: [Join our Discord](https://discord.gg/NvarFmvXKm)
+- **Issue Tracker**: [GitHub Issues](https://github.com/algorithmicsimplicity/algan/issues)
+
+---
+
+## License
+
+Algan is licensed under the MIT License (see [LICENSE](LICENSE)). Copyright &copy; Algorithmic Simplicity.