Aether Renderer Core

Aether Renderer is a minimal and sacred media compiler for image sequences — now with smart CLI, glob support, and gentle rendering feedback 🕊️

Aether Renderer Core is a lightweight, Rust-based and a sacred CLI tool to render transparent .webm, .mp4, and .gif from image sequences with alpha channel support, loop softening, and ffmpeg power.

Built with love for artists, developers, and sacred animation workflows.

---

✨ Features

• 📦 Supports ZIP archives or folders with image sequences
• 🎯 Supports frame_%04d.png (numbered) or glob patterns like scene_*.png
• 🌀 Live progress spinner with elapsed time (enabled via --verbose)
• 🎛️ Render using either --config file or inline CLI arguments
• ✨ Cross-platform (macOS, Linux, Windows)
• 🔒 Minimal dependencies, no runtime server required

Built like a triple-mode sacred core:

1. ✅ --config → full JSON or TOML-based config
2. ✅ --input + --output CLI mode
3. ✅ CLI override of config (hybrid input)

Useful for overriding output resolution, fps, or preview without rewriting full config. Aiming to be super dev-friendly — a pleasure to use.

---

🔧 Usage

1. Render using a config file

aether-renderer --config render.json

Supports .json or .toml formats.

2. Render using CLI args

aether-renderer-core --input frames.zip --output output.webm --file-pattern '*.png' --fps 30 --format webm --verbose

3. Mixed mode (config + override)

aether-renderer --config render.json --fps 60 --preview

CLI params override matching fields in the config.

---

🧾 Supported Parameters

Flag	Type	Default	Description
--input	Path	required	Folder or ZIP with image frames
--output	Path	required	Output video file path
--fps	Number	30	Frames per second
--file-pattern	String	*.png	Glob or sequence pattern for frames
--format	String	webm	Output format (webm, gif, ...)
--fade-in	Float	0.0	Seconds to fade in
--fade-out	Float	0.0	Seconds to fade out
--bitrate	String	(none)	e.g. 2500k
--crf	Number	(none)	e.g. 23 for x264 (lower = better)
--preview	Flag	false	Enables preview mode
--verbose	Flag	false	Prints detailed logs + progress bar

---

💡 Notes

• If --file-pattern contains *, glob mode is used automatically (-pattern_type glob).
• Numbered patterns like frame_%04d.png use native ffmpeg sequence.
• You can include only a partial config file — unset fields fallback to CLI or defaults.
• Designed to integrate easily with GUI and queue systems.

---

🧪 Advanced

• You can use "frame_%04d.png" for ffmpeg-native sequences.
• "*.png" or "scene*.png" will auto-activate -pattern_type glob.
• CLI --bitrate and --crf are mutually exclusive (if both set, crf takes priority).
• CLI mode will fallback to defaults where parameters are missing.
• The --fade-in and --fade-out flags apply ffmpeg's fade filter under the hood. The start of the fade out is automatically calculated from the frame count and FPS.

---

Example Configuration File (JSON)

{
  "input": "/Users/you/Downloads/frames.zip",
  "output": "/Users/you/Downloads/output.webm",
  "fps": 30,
  "format": "webm",
  "fade_in": 0.0,
  "fade_out": 0.0,
  "bitrate": null,
  "crf": 24,
  "preview": false,
  "file_pattern": "*.png",
  "verbose": true
}

Save this as example_config.json and run:

aether-renderer-core --config example_config.json

---

🧪 Usage

cargo run --release -- \
  --input ./frames \
  --output my.webm \
  --fps 30 \
  --format webm \
  --fade-in 1 \
  --fade-out 1 \
  --bitrate 2M \
  --crf 23 \
  --preview

📂 Your input folder should contain files like:

frame_0000.png
frame_0001.png
frame_0002.png
...

---

You can now also pass a .zip file containing frames:

cargo run -- --input ./my-frames.zip --output my.webm --fps 30 --format webm

📂 Your input folder or ZIP file must contain images named like:

frame_0000.png
frame_0001.png
frame_0002.png
...

Alpha-enabled PNGs are recommended for transparent .webm.

---

Convert to gif file with transparent background:

cargo run -- --input ./my-frames.zip --output my.gif --fps 30 --format gif

(Just make sure ffmpeg is installed)

---

📦 Download prebuilt binaries

prebuilds for linux, mac & windows can be found under releases in github repository.

🛠️ Download prebuilt binaries from the Releases page.

---

🧰 Requirements

• Rust & Cargo installed: https://rustup.rs
• ffmpeg must be installed and accessible in your system path

---

🧪 Tests

This project contains both unit tests and integration tests. The unit tests live next to the code they verify (for example in src/utils/unzip_frames.rs) while the integration tests reside in tests/integration.rs.

Run all tests using Cargo:

cargo test

The integration suite relies on ffmpeg being available on your system. If ffmpeg is missing, the rendering test is skipped but all other tests still run.

---

📦 Example ZIP

You can test the renderer using the provided frame sequence:

sacred-stars.zip

Run it like this:

cargo run -- --input examples/sacred-stars.zip --output demo.webm --fps 30 --format webm

This will generate a loopable .webm video with alpha.

---

✨ Example Output

See full demo here (just started): Webpage demo

Here’s one frame from the sacred animation:

---

✨ Example Animation

▶️ Watch output video

---

🔮 Roadmap

• Render .png → .webm (with alpha)
• Support .mp4 export
• Add bitrate / CRF quality control
• --fade-in, --fade-out for soft loops
• Handle errors & missing frames gracefully
• Add optional CLI preview
• Begin GUI version with Tauri (aether-renderer) 🌟

---

🧹 Code Style

This project uses Rust’s official formatting standard via cargo fmt.

Before committing or opening a pull request, please run:

cargo fmt

---

🌿 License

MIT — created with sacred care by @madspaaskesen

---

🌐 Related Projects

• 🕊️ Sacred-AI
• 📈 MySiteChart
• 🛠️ MP-IT
• 🧵 DDD Favoritter

---

💛 Made with love by Sacred-AI

🙏 Made with clarity and care by @mads @ @sacred-ai 💛

🌸 Powered by Rust Lang, Rust getting started

Aether Renderer Core is the sacred heart of a lightweight animation rendering toolkit. Converts frame sequences to video with love, transparency, and full creative control.