svg2fbf 0.1.19
SVG Frame-by-Frame Animation Generator - Create optimized FBF SVG animations from SVG sequences
License: Apache-2.0
Requires Python: >=3.11
Keywords: animation, fbf, frame-by-frame, mesh-gradient, smil, svg, svg2fbf, vector-animation

<!-- Animated Header with FBF.SVG Title -->
<p align="center">
  <img src="assets/panther_bird_header.fbf.svg" alt="FBF.SVG Animated Header - Panther and Bird Animation with Title" width="100%" style="max-width: 1280px; height: auto;"/>
</p>

<h1 align="center">svg2fbf</h1>

<p align="center">
  <strong>SVG Frame-by-Frame Animation Generator</strong>
</p>

<p align="center">
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python"></a>
  <a href="https://github.com/Emasoft/svg2fbf/releases"><img src="https://img.shields.io/github/v/release/Emasoft/svg2fbf?include_prereleases" alt="Version"></a>
</p>

<p align="center">
  <a href="https://github.com/opentoonz/opentoonz"><img src="https://img.shields.io/badge/Part%20of-OpenToonz%20Open%20Source%20Effort-ff6b35?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6bTAgMThjLTQuNDEgMC04LTMuNTktOC04czMuNTktOCA4LTggOCAzLjU5IDggOC0zLjU5IDgtOCA4em0tNS01bDctNC00IDd6Ii8+PC9zdmc+" alt="Part of OpenToonz Open Source Effort"></a>
</p>

<p align="center">
  <em>FBF.SVG format is discussed here: <a href="https://github.com/opentoonz/opentoonz/issues/5346">OpenToonz Issue #5346</a> - bringing vector frame-by-frame animation to the web</em>
</p>

---

> **⚠️ ALPHA SOFTWARE**: svg2fbf is currently in **alpha development**. While functional and tested, the API, command-line interface, and FBF format specification may change between releases. Use in production with caution and expect breaking changes until the stable 1.0 release. Check the [releases page](https://github.com/Emasoft/svg2fbf/releases) for the latest version.

---

## Table of Contents

- [About FBF.SVG Format](#about-fbfsvg-format)
  - [Design Principles](#design-principles)
  - [Format Specification & Schema](#format-specification--schema)
- [FBF.SVG Official Logo](#fbfsvg-official-logo)
- [Comparison to Other Web Vector Animation Formats](#comparison-to-other-web-vector-animation-formats)
  - [🏆 FBF.SVG vs. The Competition: Web & Mobile](#-fbfsvg-vs-the-competition-web--mobile)
  - [💡 The Verdict](#-the-verdict)
  - [Understanding the Difference: Formats vs. Implementation Methods](#understanding-the-difference-formats-vs-implementation-methods)
  - [Why FBF.SVG Stands Out: A Standard Image File, Not Code](#why-fbfsvg-stands-out-a-standard-image-file-not-code)
  - [📚 Full Documentation](#-full-documentation)
- [Description](#description)
  - [Key Features](#key-features)
- [Output Examples](#output-examples)
- [Requirements](#requirements)
- [Installation](#installation)
  - [Install uv](#install-uv)
  - [Install svg2fbf](#install-svg2fbf)
  - [Alternative Installation Methods](#alternative-installation-methods)
  - [Verify Installation](#verify-installation)
  - [Upgrading](#upgrading)
  - [Uninstalling](#uninstalling)
- [SVG ViewBox Repair Utility](#svg-viewbox-repair-utility)
  - [Why ViewBox Repair?](#why-viewbox-repair)
  - [Automatic Dependency Installation](#automatic-dependency-installation)
  - [Usage](#usage)
  - [Animation Sequence Mode](#animation-sequence-mode)
  - [Example Output](#example-output)
- [Quick Start](#quick-start)
  - [Basic Usage](#basic-usage)
  - [Using FBF Generation Cards](#using-fbf-generation-cards)
  - [Animation Types](#animation-types)
  - [Generate an Animated Button](#generate-an-animated-button)
- [CLI Parameters](#cli-parameters)
  - [Core Options](#core-options)
  - [Advanced Options](#advanced-options)
  - [Metadata Options](#metadata-options)
  - [Animation Types](#animation-types-1)
- [FBF Generation Cards](#fbf-generation-cards)
  - [What Are Generation Cards?](#what-are-generation-cards)
  - [Using Generation Cards](#using-generation-cards)
  - [How svg2fbf Works](#how-svg2fbf-works)
  - [Advanced Capabilities: Streaming & Interactive Visual Communication](#advanced-capabilities-streaming--interactive-visual-communication)
  - [SVG 2.0 Mesh Gradient Support](#svg-20-mesh-gradient-support)
- [Input Frame Requirements](#input-frame-requirements)
  - [File Naming](#file-naming)
  - [SVG Format Requirements](#svg-format-requirements)
  - [Resources and Assets](#resources-and-assets)
- [Documentation](#documentation)
- [Tools & Scripts](#tools--scripts)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Origin](#origin)

---

## About FBF.SVG Format

**FBF.SVG** (Frame-by-Frame SVG) is a proposed **candidate substandard of the SVG specification**, analogous to SVG Tiny and SVG Basic. It defines a constrained, optimized profile for declarative frame-by-frame animations that are valid SVG 1.1/2.0 documents with additional structural and conformance requirements.

<p align="center">
  <img src="assets/quote_aqua_transparent.svg" alt="Why we need a vector video format - quote from FBF.SVG creator" width="100%" style="max-width: 1200px; height: auto;"/>
</p>

### Design Principles

The FBF.SVG format is designed around eight core principles:

1. **SVG Compatibility** - Every FBF.SVG document is a valid SVG document
2. **Declarative Animation** - Uses SMIL timing, not imperative scripting
3. **Security First** - No external resources; strict Content Security Policy compliance
4. **Optimization** - Smart deduplication and shared definitions minimize file size
5. **Validatability** - Mechanically validatable against formal schema
6. **Self-Documentation** - Comprehensive embedded metadata in RDF/XML format
7. **Streaming Architecture** - Unlimited real-time frame addition without playback interruption
8. **Interactive Visual Communication** - Bidirectional LLM-to-user visual interaction protocol

### Format Specification & Schema

**📂 [FBF.SVG Format Standard](FBF.SVG/)** — Complete format specification in dedicated folder

Core documents:
- **📋 [Specification](FBF.SVG/FBF_SVG_SPECIFICATION.md)** - Complete format specification
- **📐 [XML Schema (XSD)](FBF.SVG/fbf-svg.xsd)** - Formal schema definition for validation
- **📊 [Metadata Spec](FBF.SVG/FBF_METADATA_SPEC.md)** - RDF/XML metadata requirements
- **📝 [Format Guide](FBF.SVG/FBF_FORMAT.md)** - Technical implementation details
- **📄 [Proposal](FBF.SVG/FBF_SVG_PROPOSAL.md)** - Original proposal with use cases

The specification defines two conformance levels:
- **FBF.SVG Basic** - Core structural and animation requirements
- **FBF.SVG Full** - Adds comprehensive RDF/XML metadata

The **svg2fbf** tool generates FBF.SVG Full conformant documents.

---

## FBF.SVG Official Logo:

<div align="center">
  <a href="https://github.com/Emasoft/svg2fbf">
    <picture>
      <source media="(prefers-color-scheme: light)" srcset=".github/images/fbf_svg_logo_plain_white.svg">
      <source media="(prefers-color-scheme: dark)" srcset=".github/images/fbf_svg_logo_plain_black.svg">
      <img alt="FBF.SVG Official Logo" src=".github/images/fbf_svg_logo_plain_white.svg" width="100%" style="max-width: 80%; height: auto;">
    </picture>
  </a>
</div>


---

## Comparison to Other Web Vector Animation Formats

**🎯 FBF.SVG is a Perfectly Standard SVG Image File**

FBF.SVG files are **100% standard SVG images** — nothing more, nothing less:
- ✅ **NO JavaScript code** inside the file
- ✅ **NO CSS code** inside the file
- ✅ **NO external dependencies**
- ✅ Just pure, standard SVG markup (XML)

**Compatible with millions of software tools:**
- Opens in **any web browser** (Chrome, Firefox, Safari, Edge)
- Opens in **any SVG editor** (Inkscape, Illustrator, Affinity Designer, CorelDRAW)
- Opens in **any image viewer** that supports SVG
- Opens in **video editors** (Premiere, Final Cut, DaVinci Resolve, Kdenlive)
- Opens in **design tools** (Figma, Sketch, Canva)
- Works in **mobile apps** (iOS, Android native SVG support)

**The ZERO CODE Advantage:** FBF.SVG is the **only** web vector animation format that contains **ZERO CODE**:
- ✅ **0 CODE to create** — Use visual tools (Inkscape, Krita, OpenToonz, Blender)
- ✅ **0 CODE in the file** — Pure SVG image, no JavaScript, no CSS
- ✅ **0 CODE to edit** — Edit output in any SVG graphic application
- ✅ **0 CODE to play** — Native browser support, open and it animates

This comparison highlights what makes FBF.SVG unique in the web animation ecosystem. Questions are framed to show capabilities that matter for professional animation workflows.

**📊 [View Full Detailed Comparison Tables](FBF.SVG/COMPARISON_TABLE.md)** — Complete comparison with **separate detailed tables for web formats and mobile platforms**, plus all formats, tools, pricing, and 78 documented references

### 🏆 FBF.SVG vs. The Competition: Web & Mobile

**One format. Zero code. Works everywhere.** This comparison evaluates the most popular alternatives across web and mobile to show why FBF.SVG is superior.

| **What Makes a Great Animation Format?** | **🎯 FBF.SVG** | **Lottie** (Bodymovin) | **OCA** (Open Cel) | **Rive** | **Spine** | **Alembic** (.abc) |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| **Output is a standard SVG image file?** | ✅ **YES!** | ❌ NO, outputs JSON | ❌ NO, outputs JSON+PNG | ❌ NO, outputs .riv binary | ❌ NO, outputs binary+atlas | ❌ NO, outputs .abc scene data (interchange format) |
| **Compatible with millions of SVG tools?** | ✅ **YES!** (Inkscape, Illustrator, etc.) | ❌ NO, proprietary format | ❌ NO, limited to animation tools | ❌ NO, proprietary format | ❌ NO, proprietary format | ❌ NO, requires 3D/VFX tools |
| **Playable in any app that supports SVG 1.1?** | ✅ **YES!** | ❌ NO, requires JavaScript library | ❌ NO, must export to video first | ❌ NO, requires runtime library | ❌ NO, requires runtime library | ❌ NO, requires 3D software (Maya, Houdini, Blender) |
| **Can artists create without coding?** | ✅ **YES!** | ✅ YES, but requires Adobe After Effects ($275/yr subscription) | ✅ **YES!** using Krita/Blender/OpenToonz | ✅ YES, but free version has feature limits | ✅ YES, but requires purchase ($70-330 one-time) | ✅ YES, using 3D tools (Maya, Houdini, Blender) |
| **Can play without JavaScript?** | ✅ **YES!** | ❌ NO, requires lottie-web.js library | ✅ YES, if exported as video (loses interactivity) | ❌ NO, requires Rive runtime library | ❌ NO, requires Spine runtime library | N/A (data exchange format, not playback) |
| **Can artists edit output without coding?** | ✅ **YES!** in any SVG editor (Inkscape, Illustrator, Boxy SVG, etc.) | ❌ NO, requires Adobe After Effects | ✅ **YES!** in Krita/Blender/OpenToonz | ❌ NO, requires Rive Editor | ❌ NO, requires Spine Editor | ✅ YES, in 3D/VFX software |
| **Can deploy without programmer's help?** | ✅ **YES!** | ❌ NO, developer must integrate lottie-web.js | ✅ **YES!** (as video file) | ❌ NO, developer must integrate Rive runtime | ❌ NO, developer must integrate Spine runtime | ❌ NO, production pipeline format (not for end-user deployment) |
| **Free creation tools available?** | ✅ **YES, $0!** (Inkscape, Krita, Blender, etc.) | ❌ NO, requires After Effects subscription ($275/year) | ✅ **YES, $0!** (Krita, Blender, OpenToonz) | ✅ YES, but $168-540/year for professional features | ❌ NO, requires purchase ($70-330 one-time) | ✅ YES, Blender is free (Maya/Houdini are paid) |
| **Free runtime/playback libraries?** | ✅ **YES, $0!** (native browser SVG support) | ✅ YES, $0 (lottie-web is MIT license) | ✅ YES, $0 (no runtime needed if exported as video) | ✅ YES, $0 (Rive runtimes are MIT license) | ✅ YES, $0 (Spine runtimes are free, see license) | N/A (interchange format, not runtime) |
| **Per-app licensing fees for mobile?** | ✅ **NO, $0!** | ✅ NO, $0 | ✅ NO, $0 | ✅ NO, $0 | ❌ NO normally, but YES $3,300/app for enterprise license | N/A (not used in mobile apps) |
| **Per-install runtime fees?** | ✅ **NO, $0!** | ✅ NO, $0 | ✅ NO, $0 | ✅ NO, $0 | ✅ NO, $0 | N/A |
| **Export fees for production use?** | ✅ **NO, $0!** | ✅ NO, $0 | ✅ NO, $0 | ❌ YES, requires paid subscription ($168-540/year) for full features | ✅ NO, $0 | ✅ NO, $0 (open source) |
| **Revenue sharing required?** | ✅ **NO!** | ✅ NO | ✅ NO | ✅ NO | ✅ NO | ✅ NO |
| **Edit output in standard graphic apps?** | ✅ **YES!** in Inkscape, Illustrator, Affinity Designer, etc. | ❌ NO, requires After Effects | ✅ YES, in animation apps (Krita, Blender, OpenToonz) | ❌ NO, requires Rive Editor | ❌ NO, requires Spine Editor | ❌ NO, requires 3D/VFX tools (not 2D graphic apps) |
| **Can edit output then re-export to same format?** | ✅ **YES!** (edit SVG → save as SVG) | ❌ NO, cannot round-trip (AE → JSON, but JSON ↛ AE) | ✅ YES, within same animation app | ❌ NO, cannot round-trip | ❌ NO, cannot round-trip | ✅ YES, within 3D tools |
| **Usable as exchange format between apps?** | ✅ **YES!** (SVG is universal standard) | ❌ NO, locked to After Effects | ✅ **YES!** (OCA's main purpose: interchange) | ❌ NO, locked to Rive Editor | ❌ NO, locked to Spine Editor | ✅ **YES!** (Alembic's main purpose: VFX interchange) |
| **Based on official W3C web standard?** | ✅ **YES!** (SVG 1.1/2.0 standard) | ❌ NO, proprietary spec (though open-source) | ❌ NO, community format (GPL-3.0) | ❌ NO, proprietary format | ❌ NO, proprietary format | ❌ NO, open VFX standard (Lucasfilm/Sony) |
| **Works on web in all browsers?** | ✅ **YES!** natively (no libraries needed) | ✅ YES, requires adding lottie-web.js library (~160KB) | ✅ YES, if exported as video (HTML5 video tag) | ✅ YES, requires adding Rive runtime library | ✅ YES, requires adding Spine runtime library | ❌ NO, scene interchange format (not for web playback) |
| **Works in iOS mobile apps?** | ✅ **YES!** using free SVG libraries (SVGKit, Macaw, etc.) | ✅ YES, using lottie-ios library | ✅ YES, if exported as video (AVPlayer) | ✅ YES, using rive-ios library | ✅ YES, using spine-ios library | ❌ NO, production pipeline format (not for mobile) |
| **Works in Android mobile apps?** | ✅ **YES!** using free SVG libraries (AndroidSVG, etc.) | ✅ YES, using lottie-android library | ✅ YES, if exported as video (VideoView) | ✅ YES, using rive-android library | ✅ YES, using spine-android library | ❌ NO, production pipeline format (not for mobile) |
| **Works in video games and consoles?** | ✅ **YES!** as texture/sprite sequence (Unity, Godot, Unreal, etc.) | ❌ NO, requires web runtime (not available) | ❌ NO, video format not suitable for games | ❌ NO, runtime not available on consoles | ✅ YES, but Spine is designed for games (requires runtime) | ⚠️ PARTIAL, engines can import .abc for 3D assets (not runtime animation) |
| **Imports into video editors (Premiere, Final Cut)?** | ✅ **YES!** as image sequence or direct import | ❌ NO, must convert to video first | ✅ YES, exports as video natively | ❌ NO, must convert to video first | ❌ NO, must convert to video first | ✅ YES, via 3D render pipeline |
| **Self-contained single file?** | ✅ **YES!** everything embedded in one SVG | ✅ YES, single JSON file (images as base64) | ❌ NO, JSON + separate PNG frame files | ✅ YES, single .riv file | ❌ NO, binary + separate image atlas file | ✅ YES, single .abc file |

**📝 Note on Alembic:** Alembic is included in this comparison because it's sometimes suggested for exporting animations from OpenToonz. **Alembic IS valuable for interoperability** - it's a **scene hierarchy editing format** that allows OpenToonz to exchange layered 2D/3D scene hierarchies (including z-depth for parallax effects) with other animation tools like Blender, Maya, and Houdini. However, **Alembic and FBF.SVG serve different purposes that don't interfere with each other**: Alembic is for **editing** (scene hierarchy interchange between professional tools), while FBF.SVG is for **output** (deployable vector video standard). Alembic cannot be played in browsers, mobile apps, or displayed directly as animation for public consumption. Use Alembic for production pipeline interchange (OpenToonz ↔ Blender), and FBF.SVG (or video export) for deploying animations to end users.

### 💡 The Verdict

**FBF.SVG is the ONLY format that:**
- ✅ Is a standard SVG image (not code, not proprietary data)
- ✅ Requires ZERO code at every stage (create, edit, play)
- ✅ Costs $0 for everything (tools, runtime, per-app, exports)
- ✅ Works EVERYWHERE (web, mobile, desktop, video editors, games)
- ✅ Opens in millions of applications (Inkscape, Illustrator, Final Cut, browsers, mobile apps, game engines, etc.)
- ✅ Eliminates need for programmers (artists-only workflow)

**Table Legend:**
- ✅ **YES** = Fully supported without limitations
- ✅ YES, but [condition] = Supported with specific requirement or cost
- ❌ NO, [reason] = Not supported, with explanation
- ❌ **NO** = Not supported at all

### Understanding the Difference: Formats vs. Implementation Methods

It's important to distinguish between **deliverable animation formats** (what you ship) and **implementation methods** (how you code them):

**Deliverable Formats (this table):**
- **FBF.SVG** — Self-contained SVG file (0 code required)
- **Lottie** — JSON file + JavaScript runtime (code required)
- **Rive** — .riv file + proprietary runtime (code required)
- **Adobe Animate** — Various exports (SVG, Canvas, Video)

**Implementation Methods (NOT competing formats):**
- **SMIL** — Part of SVG standard (FBF.SVG uses this internally!)
- **CSS Animations** — Requires writing CSS code
- **Web Animations API** — Requires writing JavaScript code
- **JavaScript Libraries** — Requires writing/loading code (Snap.svg, GSAP, etc.)

**Why this matters:** FBF.SVG uses SMIL internally, but that's transparent to users. You never write SMIL code — you create frames visually and svg2fbf generates the animation automatically. In contrast, CSS and WAAPI require you to write code yourself.

### Why FBF.SVG Stands Out: A Standard Image File, Not Code

Looking at the table above, FBF.SVG is the **only deliverable format** that is a **pure image file with ZERO CODE**:

**📄 It's Just an Image File!**

FBF.SVG output is a **perfectly standard SVG image file** — the same format used for logos, icons, and illustrations everywhere:
- **Not a code file** — It's an image, like a .jpg or .png
- **Not a data file** — It's not JSON, XML, or binary data that needs interpretation
- **Not a script** — Contains zero lines of JavaScript or CSS
- **Just SVG** — Pure W3C SVG markup, understood by millions of applications

**🌍 Universal Compatibility:**

> **"Anything can play an FBF.SVG video. Anything! If it supports SVG 1.1, it can reproduce it!"**

**This means:**
- ✅ Open it in **Adobe Illustrator** — it works
- ✅ Open it in **Inkscape** — it works and you can edit it
- ✅ Open it in **Google Chrome** — it works and animates
- ✅ Open it in **Final Cut Pro** — it works
- ✅ Use it in **game engines** (Unity, Godot, etc.) — it works as texture sequence
- ✅ Send it in an **email** — recipient can open it, no special software
- ✅ Upload to **any website** — it just works, no code deployment
- ✅ Import into **any design tool** — Figma, Sketch, Canva, all work

**🎯 ZERO CODE at Every Stage:**
1. **Creation** — Draw frames in Inkscape/Krita/Blender, no coding
2. **Processing** — svg2fbf generates the image file, no coding
3. **The File Itself** — Pure SVG image, contains zero code
4. **Editing** — Edit the image in any SVG graphic app, no coding
5. **Playback** — Open the image file in browser, it animates (no JavaScript needed)

**🎨 Artist-Friendly Workflow:**
- Create animation frames in familiar visual tools
- No need to learn coding, JavaScript, or CSS
- Edit output directly in Inkscape, Illustrator, etc.
- True round-trip workflow: edit → export → edit again

**🛠️ Developer-Friendly Format:**

A company that wants to create a graphic editor for FBF.SVG **doesn't need to support the complexity of a CSS rendering engine or a JavaScript runtime!** All it needs is to support the plain, bare **SVG 1.1 or SVG 2.0 standard**.

- ✅ **Simple implementation** — Just implement SVG standard
- ✅ **No CSS engine required** — Zero CSS to parse or render
- ✅ **No JavaScript runtime required** — Zero scripts to execute
- ✅ **Lower complexity** — Smaller codebase, fewer bugs
- ✅ **Faster development** — Build tools faster
- ✅ **Better performance** — Native rendering, no scripting overhead

**🔓 No Vendor Lock-in:**
- Output is standard SVG (works in any SVG tool)
- Not tied to proprietary editor or runtime
- Can switch tools at any time
- Future-proof: based on W3C standard

**📦 Self-Contained & Universal:**
- Single SVG file, no external dependencies
- No JavaScript bundle to load (~0KB vs. Lottie's 160KB)
- Works everywhere: web, print, video editors, presentations
- Native browser performance, hardware-accelerated

**💰 Economic Advantages:**

> **"With FBF.SVG there is no need to hire programmers anymore to create animations. Artists are all you need."**

- **Lower production costs** — No need for programming team
- **Faster hiring** — Artists are easier to find than animation programmers
- **Simpler workflow** — Artists work with familiar visual tools
- **No code maintenance** — Zero codebase to debug or update
- **Apache 2.0 license** — Permissive, commercial-friendly
- **Works with free tools** — Inkscape, Krita, OpenToonz, Blender
- **No subscription fees** — No runtime licensing costs
- **No distribution fees** — Free for commercial streaming

**When to Choose FBF.SVG:**
- ✅ Frame-by-frame vector animation (cartoons, anime, traditional animation)
- ✅ Want complete workflow without writing any code
- ✅ Need standard SVG output editable in graphic applications
- ✅ Require self-contained files with 0 external dependencies
- ✅ Building with free/open source tools
- ✅ Need true bidirectional workflow (edit anywhere, anytime)
- ✅ JavaScript-free playback for performance/security
- ✅ Commercial projects requiring permissive licensing

**When to Consider Alternatives:**
- **Lottie**: Already invested in After Effects, comfortable with JavaScript runtime dependency
- **Rive**: Need interactive game-like animations with complex state machines and don't mind proprietary format
- **Adobe Animate**: Already have Creative Cloud subscription, need multiple export formats
- **Spine**: Building 2D games with skeletal animation, need advanced rigging

### 📚 Full Documentation

The table above is a curated selection of the most important comparisons. For complete details:

📊 **[View Full Detailed Comparison Tables](FBF.SVG/COMPARISON_TABLE.md)** with:
- **Web Animation Formats** — Complete 8-format comparison table with all technical details
- **Mobile Animation Formats** — Dedicated mobile table with iOS/Android library details, per-app fees, and hidden costs
- **JavaScript Libraries** — 7 animation libraries compared
- **Animation Authoring Tools** — 8 creation tools compared
- **78 Documented References** — Every claim backed by official sources

**Cost Breakdown Examples:**
- **5 mobile apps, 1 year**: FBF.SVG $0 vs Lottie $275 vs Rive $168-540 vs Spine Enterprise (per-product) $16,500
- **Free SVG libraries**: iOS (SVGKit, SVGView, Macaw), Android (AndroidSVG, SVG-Android), Cross-platform (React Native SVG, Flutter SVG) - all MIT/Apache 2.0

---

## Description

**svg2fbf** is a command-line tool that transforms sequences of SVG files into FBF (Frame-by-Frame) SVG animations using SMIL declarative animation. The tool processes a directory of SVG frames, applies element deduplication and optimization algorithms, and generates a single, self-contained animated SVG document conformant to the FBF.SVG specification.

### Key Features

#### Core Animation Features
- 🎬 **Frame-by-frame animation** - Sequential SVG frame composition with SMIL timing control
- 🔄 **Element deduplication** - Hash-based identification and elimination of redundant SVG elements across frames
- 📦 **Gradient optimization** - Intelligent merging of identical gradient definitions
- 🎞️ **Animation modes** - Eight playback modes (once, loop, pingpong, with forward/reverse variants)
- 🖼️ **ViewBox normalization** - Automatic transformation of heterogeneous frame dimensions
- 🌈 **SVG 2.0 mesh gradients** - Native support with conditional JavaScript polyfill injection
- 📋 **Structured metadata** - RDF/XML metadata conformant to Dublin Core and custom FBF vocabulary
- ⚙️ **FBF Generation Cards** - Declarative YAML-based project configuration for reproducible builds

#### Advanced Capabilities
- 🌊 **Streaming architecture** - Real-time frame appending without playback interruption via frames-at-end design
- 🤖 **LLM visual protocol** - Bidirectional visual communication interface for AI-to-user interaction
- 📡 **Interactive coordination** - SVG element identification and coordinate-based user input handling
- 🎯 **Dynamic composition** - Runtime modification of three Z-order extension points (background, foreground, overlay)
- 🔄 **Progressive rendering** - Frame definitions positioned after animation structure for streaming optimization

---

## Output Examples

![SVG Animation Examples](assets/svg_animation_examples_header_onion_skin.webp)

Here are examples of FBF animations generated by svg2fbf. All examples are located in the `examples/` directory.

### 1. 🎯 CODE-FREE Interactive Splat Button
<p align="center">
  <img src="assets/splat_button.fbf.svg" alt="Splat Button Animation - Click Me!" width="300"/>
</p>

**✨ ZERO JavaScript Required!** Interactive button with click-triggered splash effect animation - pure SVG, no code needed!

- **Frames**: 11
- **FPS**: Variable (pingpong loop)
- **Trigger**: Click event (`begin="click"`)
- **Features**: Click-triggered animation, effects, filters, blending modes
- **Output**: `examples/splat_button/fbf_output/splat_button.fbf.svg`
- **Config**: [`examples/splat_button/splat_button.yaml`](examples/splat_button/splat_button.yaml)

*Click the button above to trigger the animation!*

> **💡 Future Enhancement**: We're planning to add callback function support, allowing you to specify custom JavaScript callbacks when the animation completes.

### 2. Panther and Bird
<p align="center">
  <img src="assets/panther_bird.fbf.svg" alt="Panther and Bird Animation" width="100%" style="max-width: 1280px; height: auto;"/>
</p>

Cinematic-quality animation featuring a prowling panther and flying bird with synchronized movement.

- **Frames**: 17 (panther), 9 (bird) - independently animated
- **Dimensions**: 1280×720px (widescreen format)
- **FPS**: Variable (0.75s per frame)
- **Features**:
  - Multi-entity animation (separate animation cycles)
  - Complex vector artwork with gradients
  - Optimized file size through intelligent element reuse
  - Professional-grade character animation
- **Output**: `examples/panther_bird/fbf_output/panther_bird.fbf.svg`

This example demonstrates advanced FBF.SVG capabilities, including multiple independently-cycling animated groups sharing the same scene.

### 3. 🚶 Walk Cycle Animation
<p align="center">
  <img src="assets/walk_cycle.fbf.svg" alt="Walk Cycle Animation" width="512"/>
</p>

Professional character walk cycle demonstrating classic animation principles.

- **Frames**: Multiple keyframes
- **Dimensions**: 512×512px
- **FPS**: Variable
- **Features**:
  - Classic animation walk cycle principles
  - Smooth looping motion
  - Character animation fundamentals
  - Ideal for learning frame-by-frame animation techniques
- **Output**: `examples/walk_cycle/fbf_output/walk_cycle.fbf.svg`
- **Config**: [`examples/walk_cycle/walk_cycle.yaml`](examples/walk_cycle/walk_cycle.yaml)

Perfect for studying how traditional animation principles translate to FBF.SVG format.

### 4. 🦅 Seagull Flight Animation
<p align="center">
  <img src="assets/seagull.fbf.svg" alt="Seagull Animation" width="400"/>
</p>

Simple seagull flying animation with basic shapes and gradients.

- **Frames**: 10
- **FPS**: 12
- **Features**:
  - Simple looping animation
  - Basic shapes and gradients
  - Lightweight file size
  - Great for learning FBF.SVG basics
- **Output**: `examples/seagull/fbf_output/seagull.fbf.svg`
- **Config**: [`examples/seagull/seagull.yaml`](examples/seagull/seagull.yaml)

### 5. 🎭 Anime Character Animation
<p align="center">
  <img src="assets/anime_girl.fbf.svg" alt="Anime Girl Animation" width="400" height="400" />
</p>

Complex character animation.

- **Frames**: 35
- **FPS**: 24
- **Features**:
  - Complex character animation
  - Mesh gradients and detailed artwork
  - High frame count for smooth motion
  - Advanced SVG techniques
- **Output**: `examples/anime_girl/fbf_output/anime_girl.fbf.svg`
- **Config**: [`examples/anime_girl/anime_girl.yaml`](examples/anime_girl/anime_girl.yaml)

---

## Requirements

- **Python**: ≥3.11
- **[uv](https://github.com/astral-sh/uv)**: Package and tool manager

---

## Installation

svg2fbf is installed as a **uv tool**, which makes it available globally on your system.

### Install uv

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Install svg2fbf

Choose the release channel that fits your needs:

#### Stable Release (Recommended for Production)

```bash
# Install from PyPI (recommended - production-ready)
uv tool install svg2fbf --python 3.11

# Or install from GitHub stable branch
uv tool install git+https://github.com/Emasoft/svg2fbf.git@master --python 3.11
```

#### Pre-Release Channels

```bash
# Release Candidate (rc) - Final testing before stable
uv tool install git+https://github.com/Emasoft/svg2fbf.git@review --python 3.11

# Beta - Bug fixes and testing
uv tool install git+https://github.com/Emasoft/svg2fbf.git@testing --python 3.11

# Alpha - Latest features (may be unstable)
uv tool install git+https://github.com/Emasoft/svg2fbf.git@dev --python 3.11
```

**Release Pipeline:**
- **Alpha** (dev branch) → Active development, new features
- **Beta** (testing branch) → Bug hunting and fixes
- **RC** (review branch) → Release candidate, final approval
- **Stable** (master branch) → Production-ready, published to PyPI

### Alternative Installation Methods

<details>
<summary>Click to expand alternative installation options</summary>

#### Install from GitHub Releases

```bash
# This script automatically finds and installs the latest stable release
LATEST_URL=$(curl -s https://api.github.com/repos/Emasoft/svg2fbf/releases/latest | grep "browser_download_url.*\.whl" | cut -d '"' -f 4)
uv tool install "$LATEST_URL" --python 3.11
```

#### Install from Local Wheel File

```bash
# Install from local wheel in dist/ directory
uv tool install dist/svg2fbf-*.whl --python 3.11

# Or with absolute path
uv tool install /path/to/svg2fbf-*.whl --python 3.11
```

</details>

### Verify Installation

```bash
# Check version
svg2fbf --version

# Display help
svg2fbf --help
```

**That's it!** All dependencies (including Node.js and Puppeteer for the viewBox repair utility) will be **automatically installed** on first use.

### Upgrading

#### Check Current Version

```bash
# See what version you have installed
svg2fbf --version
```

#### Upgrade to Latest Stable

```bash
# Upgrade from PyPI (recommended)
uv tool upgrade svg2fbf

# Or reinstall from GitHub master branch
uv tool install git+https://github.com/Emasoft/svg2fbf.git@master --python 3.11
```

#### Upgrade to Specific Release Channel

```bash
# Reinstall with release candidate (rc)
uv tool install git+https://github.com/Emasoft/svg2fbf.git@review --python 3.11

# Reinstall with beta
uv tool install git+https://github.com/Emasoft/svg2fbf.git@testing --python 3.11

# Reinstall with alpha (bleeding edge)
uv tool install git+https://github.com/Emasoft/svg2fbf.git@dev --python 3.11
```

#### Force Reinstall (Clean Upgrade)

If you encounter issues, perform a clean reinstall:

```bash
# Recommended: Uninstall then install (clean reinstall)
uv tool uninstall svg2fbf
uv tool install svg2fbf --python 3.11
```

### Uninstalling

Remove svg2fbf completely from your system:

```bash
# Uninstall svg2fbf
uv tool uninstall svg2fbf
```

**Verify uninstallation:**

```bash
# This should show "command not found" or similar
svg2fbf --version
# Or check uv tools list
uv tool list
```

**What gets removed:**
- The `svg2fbf` command
- The `svg-repair-viewbox` utility
- All dependencies installed for svg2fbf
- Python virtual environment for the tool

**What stays:**
- Your SVG files and FBF.SVG outputs
- Configuration files you created
- The `uv` package manager itself

---

## SVG ViewBox Repair Utility

svg2fbf includes a **viewBox repair utility** (`svg-repair-viewbox`) that automatically calculates and adds viewBox attributes to SVG files using Puppeteer/headless Chrome for accurate bounding box calculation.

### Why ViewBox Repair?

Many SVG files lack proper viewBox attributes, which can cause:
- Incorrect rendering dimensions
- Frame-to-frame jumping in animations
- Scaling and positioning issues

The repair utility uses Puppeteer's `getBBox()` to calculate actual content bounds including fill, stroke, and markers.

### Automatic Dependency Installation

**No manual setup required!** On first use, `svg-repair-viewbox` will automatically:

1. ✅ Detect your operating system and package manager
2. ✅ Install Node.js if not already present (using brew/apt/dnf/pacman/choco)
3. ✅ Install Puppeteer globally

Just run the command and it handles everything!

### Usage

```bash
# Repair a single SVG file
svg-repair-viewbox image.svg

# Repair multiple SVG files (animation sequence)
svg-repair-viewbox frame001.svg frame002.svg frame003.svg

# Repair all SVG files in a directory
svg-repair-viewbox /path/to/svg/directory

# Quiet mode (no progress output)
svg-repair-viewbox --quiet *.svg
```

### Animation Sequence Mode

For animation sequences, the utility uses a **union bbox strategy**:

1. Calculates individual bounding box for each frame
2. Computes union bbox that encompasses all frames
3. Applies the SAME viewBox to ALL frames

This ensures consistent dimensions across all frames, preventing frame-to-frame jumping in animations.

### Example Output

**First run** (automatic dependency installation):

```bash
$ svg-repair-viewbox /tmp/animation_frames

⚙️  First-time setup: Installing required dependencies...

======================================================================
🔧 svg-repair-viewbox Automatic Dependency Setup
======================================================================

🎯 Detected package manager: brew

📦 Installing Node.js...
✅ Node.js installed successfully (v20.10.0)

📦 Installing Puppeteer (this will download ~170MB Chromium)...
✅ Puppeteer installed successfully

======================================================================
✅ All dependencies installed successfully!
======================================================================

Found 23 SVG file(s)

======================================================================
   🎬 ANIMATION SEQUENCE VIEWBOX REPAIR
======================================================================
   Files with viewBox: 0
   Files missing viewBox: 23

   📐 Calculating union bbox across 23 frames...
      Frame 01: x=  -2.04, y=  -2.05, w= 237.19, h= 452.63
      Frame 02: x=  -2.00, y=  -2.01, w= 238.13, h= 452.21
      ...

   ✅ Union bbox: x=-2.06, y=-2.06, width=247.62, height=453.10
      This viewBox will be applied to ALL 23 frames

   🔧 Applying union viewBox to all frames...
      ✓ Frame 01: frame00001.svg
      ✓ Frame 02: frame00002.svg
      ...

   ✅ Successfully applied union viewBox to 23 frames!
======================================================================

✅ Successfully repaired 23 file(s)
```

**Subsequent runs** (dependencies already installed):

```bash
$ svg-repair-viewbox /tmp/animation_frames

Found 23 SVG file(s)

======================================================================
   🎬 ANIMATION SEQUENCE VIEWBOX REPAIR
======================================================================
   ...
```

---

## Quick Start

### Basic Usage

```bash
# Simple animation from folder
svg2fbf -i svg_frames/ -o output/ -f animation.fbf.svg -s 24

# Loop animation
svg2fbf -i frames/ -o output/ -f loop.fbf.svg -a loop -s 12

# Animation starts on click
svg2fbf -i frames/ -o output/ -f interactive.fbf.svg -s 24 -p

# Process only the first 10 frames
svg2fbf -i large_animation/ -o output/ -f preview.fbf.svg -s 12 -m 10

# Suppress status messages
svg2fbf -i frames/ -o output/ -f animation.fbf.svg -s 24 -q
```

### Using FBF Generation Cards

A **FBF Generation Card** is a declarative YAML configuration file that specifies all parameters needed to generate an FBF.SVG animation. Generation cards enable reproducible, version-controlled animation builds and serve as documentation of your animation's configuration.

Create a generation card file:

```yaml
# config.yaml
metadata:
  title: "My Animation"
  creators: "Your Name"

generation_parameters:
  input_folder: "frames/"
  output_path: "output/"
  filename: "animation.fbf.svg"
  speed: 24.0
  animation_type: "loop"
```

Run with generation card:

```bash
# Use generation card
svg2fbf my_animation_card.yaml

# Override generation card settings with CLI
svg2fbf my_animation_card.yaml --speed 30.0 --title "Custom Title"
```

**Creating Your FBF Animations:**

1. **Prepare SVG frames**: Create a sequence of SVG files (frame_001.svg, frame_002.svg, ...)
2. **Organize folder**: Place all frames in a single folder
3. **Create generation card**: Use the generation-card template or the examples cards as starting point
4. **Run svg2fbf**: Execute with your generation card
5. **Test output**: Open the generated FBF file in a browser (Google Chrome recommended for best svg standard support)

**Recommended SVG Creation Tools**:
- **[Inkscape](https://github.com/inkscape/inkscape)** - Full-featured SVG editor with mesh gradient support
- **[OpenToonz](https://github.com/opentoonz/opentoonz)** - Professional 2D animation software with SVG export
- **[Blender](https://github.com/blender/blender)** (Grease Pencil) - 3D software with powerful 2D animation tools and SVG export

---


### Animation Types

svg2fbf supports multiple animation playback modes via the `-a` or `--animation_type` parameter:

| Animation Type | Behavior | Use Case |
|----------------|----------|----------|
| `once` | START → END, then STOP | Single playback (splash screens, transitions) |
| `once_reversed` | END → START, then STOP | Reverse single playback |
| `loop` | START → END, repeat FOREVER | Continuous forward loop (background animations) |
| `loop_reversed` | END → START, repeat FOREVER | Continuous reverse loop |
| `pingpong_once` | START → END → START, then STOP | Single bounce effect |
| `pingpong_loop` | START → END → START, repeat FOREVER | Smooth character animations, breathing effects |
| `pingpong_once_reversed` | END → START → END, then STOP | Reverse bounce effect |
| `pingpong_loop_reversed` | END → START → END, repeat FOREVER | Reverse continuous bounce |

**Animation Types CLI Examples:**

```bash
# Play once then stop
svg2fbf -i frames/ -o output/ -f once.fbf.svg -s 24 -a once

# Loop forever (default for most animations)
svg