SVG Frame-by-Frame Animation Generator

FBF.SVG format is discussed here: OpenToonz Issue #5346 - bringing vector frame-by-frame animation to the web

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 for the latest version.

• About FBF.SVG Format
  • Design Principles
  • Format Specification & Schema
• FBF.SVG Official Logo
• Comparison to Other Web Vector Animation Formats
  • FBF.SVG vs. The Competition: Web & Mobile
  • The Verdict
  • Understanding the Difference: Formats vs. Implementation Methods
  • Why FBF.SVG Stands Out: A Standard Image File, Not Code
  • Full Documentation
• Description
  • Key Features
• Output Examples
• Requirements
• Installation
  • Install uv
  • Install svg2fbf
  • Alternative Installation Methods
  • Verify Installation
  • Upgrading
  • Uninstalling
• SVG ViewBox Repair Utility
  • Why ViewBox Repair?
  • Automatic Dependency Installation
  • Usage
  • Animation Sequence Mode
  • Example Output
• Quick Start
  • Basic Usage
  • Using FBF Generation Cards
  • Animation Types
  • Generate an Animated Button
• CLI Parameters
  • Core Options
  • Advanced Options
  • Metadata Options
  • Animation Types
• FBF Generation Cards
  • What Are Generation Cards?
  • Using Generation Cards
  • How svg2fbf Works
  • Advanced Capabilities: Streaming & Interactive Visual Communication
  • SVG 2.0 Mesh Gradient Support
• Input Frame Requirements
  • File Naming
  • SVG Format Requirements
  • Resources and Assets
• Documentation
• Tools & Scripts
• Troubleshooting
• Contributing
• License
• Acknowledgments
• Origin

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.

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

FBF.SVG Format Standard -- Complete format specification in dedicated folder

Core documents:

• Specification - Complete format specification
• XML Schema (XSD) - Formal schema definition for validation
• Metadata Spec - RDF/XML metadata requirements
• Format Guide - Technical implementation details
• Proposal - 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 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 -- Complete comparison with separate detailed tables for web formats and mobile platforms, plus all formats, tools, pricing, and 78 documented references

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

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.

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

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.

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

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

View Full Detailed Comparison Tables 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

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.

• 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

• 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

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

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

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.

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

• Frames: 17 (panther), 9 (bird) - independently animated
• Dimensions: 1280x720px (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.

Professional character walk cycle demonstrating classic animation principles.

• Frames: Multiple keyframes
• Dimensions: 512x512px
• 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

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

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

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

• Python: >=3.10
• uv: Package and tool manager

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

Choose the release channel that fits your needs:

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

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

If you encounter issues, perform a clean reinstall:

Remove svg2fbf completely from your system:

Verify uninstallation:

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

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.

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.

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!

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.

First run (automatic dependency installation):

Subsequent runs (dependencies already installed):

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:

Run with generation card:

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 - Full-featured SVG editor with mesh gradient support
• OpenToonz - Professional 2D animation software with SVG export
• Blender (Grease Pencil) - 3D software with powerful 2D animation tools and SVG export

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

Animation Types CLI Examples:

Animation Types Generation Card Example:

FBF Generation Cards (also called fbf-generation-cards) are declarative YAML-based configuration files that specify all parameters needed to generate a complete FBF.SVG animation. They serve as:

• Project blueprints - Complete specification of animation configuration in version-control-friendly YAML format
• Reproducible builds - Generate identical animations across different machines and time periods
• Documentation - Self-documenting animation metadata and parameters
• Automation - Enable scripted batch animation generation and CI/CD workflows

Every example in the examples/ directory includes a generation card, making it easy to understand and replicate each animation's configuration.

Generate an animation from a generation card:

For complete documentation, see FBF Generation Cards Guide

For a ready-to-use template, see Generation Card Template

For comprehensive information about generation cards and all available configuration options, see:

• FBF Generation Cards Documentation - Complete guide to creating and using generation cards

svg2fbf implements a multi-phase transformation pipeline that converts a temporally-ordered sequence of SVG documents into a single FBF.SVG animation. The transformation process applies element deduplication algorithms, gradient merging optimizations, and SMIL timing generation to produce compact, self-contained animated SVG documents.

Complete FBF Structure Tree:

Strict Element Ordering (mandatory for specification conformance):

The FBF.SVG specification mandates a deterministic hierarchical structure with precise element ordering. This structural constraint enables FBF-conformant renderers to perform efficient parsing, predictable streaming, and safe runtime composition via three designated extension points:

1. SVG root - (optional) - (required)
2. ANIMATION_BACKDROP () -- Extensibility point for layered composition
   • STAGE_BACKGROUND () -- Background layer (Z-order: behind animation, dynamic API)
   • ANIMATION_STAGE () -- Animation container
     • ANIMATED_GROUP () -- Timing orchestration
       • PROSKENION () -- Frame reference with SMIL child
   • STAGE_FOREGROUND () -- Foreground layer (Z-order: in front of animation, dynamic API)
3. OVERLAY_LAYER () -- Overlay layer (Z-order: superimposed on all, dynamic API for badges/titles/logos/subtitles/borders/PiP)
4. defs -- All reusable definitions in strict order:
   • SHARED_DEFINITIONS (first child) -- Shared elements (gradients, symbols, paths)
   • FRAME00001, FRAME00002, FRAME00003, ... (sequential) -- Individual frames
5. script (optional, last) -- Mesh gradient polyfill only

Structural Rationale:

• Streaming Optimization: Deterministic element ordering enables single-pass parsing without full DOM traversal or backtracking
• Safe Composition: Three designated extension point groups (STAGE_BACKGROUND, STAGE_FOREGROUND, OVERLAY_LAYER) permit runtime content injection without corrupting required animation structure
• Z-Order Layering: Prescribed nesting order establishes three composable layers with deterministic rendering precedence (background < animation < foreground < overlay)
• Security Validation: Structural constraints enable mechanical verification of conformance and prevention of element injection attacks

FBF.SVG provides architectural support for two advanced use cases that extend beyond traditional frame-by-frame animation:

The frames-at-end structural design enables dynamic frame appending during playback:

• Live presentations: Real-time vector conversion of presentation slides, whiteboard captures, or screen recordings
• LLM-generated content: On-demand AI generation of character poses, scene elements, or interface components
• Remote vector rendering: Resolution-independent remote desktop visualization
• Synchronized narrative visualization: Dynamic scene generation coordinated with textual or audio content

The specification's requirement that frame definitions appear after the animation control structure permits incremental frame appending without interrupting SMIL playback state, enabling streaming applications including live data visualization, interactive tutorials, and real-time generative art.

FBF.SVG supports bidirectional visual communication between language models and users through declarative SVG generation:

Traditional Text-Based Interaction: LLM emits textual procedure description - User parses natural language - Potential comprehension errors for spatial/visual tasks

FBF.SVG Visual Interaction: LLM generates interactive SVG frames - User provides coordinate-based input with element identification - LLM responds with contextual visual updates

Technical Characteristics:

• Declarative output: LLM produces pure SVG markup without imperative JavaScript/HTML/CSS code generation
• Context adaptation: Generated interfaces dynamically adjust to conversational state, user proficiency level, and device capabilities
• Bidirectional coordination: User interaction coordinates and SVG element IDs transmitted to LLM for state updates
• Deterministic execution: Declarative SVG eliminates runtime errors inherent in generated imperative code

Application Domains:

• Technical repair guidance: Component identification in circuit board diagrams with progressive detail revelation upon user selection
• Visual information retrieval: Dynamic menu generation with semantic annotations, responding to user selection with detailed data visualization
• Diagnostic analysis: Schematic generation with state visualization, interactive element selection triggering contextual explanations

This architectural approach enables language models to function as declarative visual interface generators, producing dynamic, context-specific user interfaces without requiring pre-programmed GUI implementations or imperative scripting.

For complete technical details, see:

• Section 13: Streaming Capabilities
• Section 14: Interactive Visual Communication Protocol
• FBF.SVG Full Specification

svg2fbf provides native support for SVG 2.0 mesh gradients ( elements) present in input frame documents. Mesh gradient creation is supported by SVG 2.0-conformant editors including Inkscape and other tools implementing the SVG 2.0 specification.

When mesh gradient elements are detected during processing, svg2fbf conditionally injects a lightweight JavaScript polyfill (~16KB) to ensure cross-browser rendering compatibility, including user agents lacking native SVG 2.0 mesh gradient support. This polyfill constitutes the only permissible JavaScript content in FBF.SVG documents per specification.

For a complete list of supported SVG features, see SUPPORTED_SVG_FEATURES.md.

svg2fbf accepts a sequence of SVG files as input frames. Each frame must meet these requirements:

Recommended format: Use 5-digit zero-padded numbering for best compatibility:

This format ensures proper alphabetical sorting and clear frame ordering. Other numbering schemes work but may cause sorting issues with some tools.

• Valid SVG files: Each frame must be a valid SVG 1.0, 1.1, or 2.0 document
• Supported tools: Export from Inkscape, OpenToonz, Blender (Grease Pencil), or any SVG editor
• One frame per file: Each SVG file should contain only one animation frame
• Static content: Frames must be static images (no SMIL animations or interactive elements)
• Consistent dimensions: Use the same viewBox and dimensions across all frames to avoid distortion

• External resources: Linked images, fonts, and other resources are automatically downloaded and embedded as base64 data URIs
• Embedded resources: Already-embedded base64 resources are preserved
• No external dependencies: Final FBF.SVG file is completely self-contained

• Mesh gradients: SVG 2.0 mesh gradients fully supported (Inkscape-compatible)
• Filters: Supported but may impact playback performance on slower systems
• CSS styles: Parsed and converted to SVG attributes (native SVG attributes are faster)

• SVG layers (content will be flattened)
• Nested SVG elements
• JavaScript in source frames
• SMIL animations in source frames

For detailed technical information, see Supported SVG Features.

• FBF.SVG Format Standard - Complete format specification (spec, schema, metadata, proposal)
• FBF.SVG Validator - Python validator script for FBF.SVG conformance

• FBF Generation Cards - Complete guide to generation card configuration
• Supported SVG Features - SVG 1.1 and 2.0 feature support matrix
• FBF Frame Comparator - Compare two FBF animations pixel-by-pixel for regression testing
• Getting Started - Tutorial and quick start guide
• Installation Guide - Detailed installation instructions
• ViewBox Repair Utility - Guide to using svg-repair-viewbox tool

• Developer Workflow Guide - Complete workflow using Just task runner with all available commands
• Development Guide - Development setup, testing, and building
• Contributing - Tools - Code contribution guidelines (svg2fbf, players, servers)
• Contributing - Format (WHAT/WHY) - Vision, goals, and principles of FBF.SVG standardization
• Developing - Format (HOW) - Practical procedures for contributing to specification
• Roadmap - Project timeline and areas needing help
• Changelog - Version history and changes

• License - Apache License 2.0
• Acknowledgments - Credits and attributions

• Issue Tracker - Report bugs and request features
• Discussions - Ask questions and share ideas

svg2fbf includes several validation and utility scripts to help you work with FBF.SVG files and generation cards.

The validate_fbf.py script provides comprehensive validation of FBF.SVG documents against the formal specification.

Usage:

What It Validates:

• XML well-formedness - Valid XML syntax
• SVG validity - Proper SVG namespace and attributes
• FBF structural requirements - Required elements and strict ordering
• SMIL animation correctness - Valid animation timing and frame references
• Security constraints - No external resources or forbidden scripts
• Metadata completeness - RDF/XML metadata conformance
• ID naming conventions - Proper frame and element IDs
• Frame reference integrity - Sequential frame numbering
• XSD schema validation - Optional validation against fbf-svg.xsd (requires lxml)

Exit Codes:

• 0 - Valid FBF.SVG document
• 1 - Invalid structure
• 2 - Invalid metadata
• 3 - Security violation
• 4 - XML parsing error

Conformance Levels:

• Basic: Valid structure and animation (usable FBF.SVG)
• Full: Basic + complete RDF/XML metadata + strict naming (production-ready)

Example Output:

The validate_yaml_config.py script validates FBF Generation Card (YAML) files before use.

Usage:

What It Validates:

• YAML syntax - Valid YAML structure
• File structure - Proper metadata and generation_parameters sections
• Metadata fields - Dublin Core and FBF custom fields with correct types
• Generation parameters - Valid animation settings and file paths
• Animation types - Valid playback modes (once, loop, pingpong, etc.)
• Value ranges - FPS and other numeric constraints
• Required fields - Input/output paths and essential configuration

Exit Codes:

• 0 - Valid YAML configuration
• 1 - Invalid YAML configuration (errors found)
• 2 - File not found or cannot be read

Common Validation Checks:

• Animation type must be one of: once, once_reversed, loop, loop_reversed, pingpong_once, pingpong_loop, pingpong_once_reversed, pingpong_loop_reversed
• Speed (FPS) must be between 0.1 and 120.0
• Either input_folder or frames list must be specified
• Metadata fields must be correct types (string, int, float, boolean)

Example Output:

Why Use These Validators?

• Catch errors early - Validate before processing to avoid wasted time
• Ensure conformance - Verify your FBF.SVG meets specification requirements
• Debug issues - Detailed error messages help identify problems quickly
• Quality assurance - Validate production files meet Full Conformance level
• CI/CD integration - Use exit codes in automated testing pipelines

Cause: svg2fbf cannot find .svg files in the specified directory.

Solutions:

• Verify the directory path: ls your_directory/ should show .svg files
• Ensure files have .svg extension (not .SVG or .svg.txt)
• Use absolute paths if relative paths aren't working:
  svg2fbf -i /full/path/to/frames/ -o /full/path/to/output/
• Check file permissions: ls -la your_directory/

Cause: SVG frames have inconsistent viewBox attributes.

Solutions:

• Open all frame SVGs and ensure they have identical viewBox values
• Example: All frames should have viewBox="0 0 800 600"
• Use your SVG editor to standardize the canvas size before exporting
• svg2fbf will warn you about viewBox inconsistencies

Cause: Incorrect FPS setting for the desired animation speed.

Solutions:

• Calculate target FPS: fps = total_frames / desired_duration_in_seconds
• Example: 120 frames over 5 seconds = 24 FPS
• Adjust with -s or --speed parameter:
  svg2fbf -i frames/ -o output/ -f animation.fbf.svg -s 24
• Common FPS values:
  • 12 FPS: Choppy, retro style
  • 24 FPS: Cinema standard
  • 30 FPS: Smooth animation
  • 60 FPS: Very smooth, high-quality

Cause: Lack of element deduplication.

Solutions:

• Ensure consistent elements across frames (identical objects should be pixel-perfect duplicates)
• Remove unnecessary complexity from source SVGs:
  • Simplify paths in your SVG editor (Path - Simplify in Inkscape)
  • Merge similar colors
  • Remove hidden or duplicate elements
• Check deduplication is working: svg2fbf should report shared elements found

Cause: Generated FBF.SVG doesn't meet format requirements.

Solutions:

• Run the validator to see specific errors:
  python scripts/validate_fbf.py output/animation.fbf.svg --verbose
• Common validation issues:
  • External resources: Embed all images as data URIs (svg2fbf does this automatically)
  • Scripts: Remove