framesvg 0.2.0

Convert animated GIFs to animated SVGs.

Convert animated GIFs to animated SVGs.

framesvg is a web app, command-line tool, and Python library that converts animated GIFs into animated SVGs. It leverages the power of VTracer for raster-to-vector conversion, producing smooth, scalable, and true vector animations. This is a significant improvement over embedding raster images (like GIFs) directly within SVGs, as framesvg generates genuine vector output that plays automatically and scales beautifully. Ideal for readmes, documentation, and web graphics.

You can try it now at framesvg.romelium.cc

Why Use framesvg?

• True Vector Output: Unlike simply embedding a GIF within an SVG, framesvg creates a true vector animation. This means:
  • Scalability: The SVG can be resized to any dimensions without losing quality.
  • Smaller File Size (Potentially): For many GIFs, the resulting SVG will be smaller, especially for graphics with large areas of solid color or simple shapes. Complex, photographic GIFs may be larger, however.
• Automatic Playback: The generated SVGs are designed to play automatically in any environment that supports SVG animations (web browsers, GitHub, many image viewers, etc.).
• Easy to Use: Simple command-line interface and a clean Python API.
• Customizable: Control the frame rate and fine-tune the VTracer conversion process for optimal results.
• Network Compression: SVGs are text-based and highly compressible. Web servers typically use gzip or Brotli compression, significantly reducing the actual transfer size of SVG files compared to GIFs (which are already compressed and don't utilize this). This leads to much faster loading times than GIFs. You can see it here.

Examples

There is a dedicated and more better example page here

The following examples demonstrate the conversion of GIFs (left) to SVGs (right) using framesvg.

More Examples

Complex Examples (Transparent Backgrounds)

These examples demonstrate binary color mode. All bright colors in binary color mode turns transparent. (If they appear dark, it is due to the transparency. They will look correct on light backgrounds)

Installation

Using pipx (Recommended for CLI-only use)

If you primarily intend to use framesvg as a command-line tool (and don't need the Python library for development), pipx is the recommended installation method. pipx installs Python applications in isolated environments, preventing dependency conflicts with other projects.

pipx install framesvg

To install pipx if you don't already have it:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

(You may need to restart your shell after installing pipx.)

Using pip

The easiest way to install framesvg is via pip:

pip install framesvg

This installs both the command-line tool and the Python library.

From Source

1. Clone the repository:

   git clone https://github.com/romelium/framesvg
   cd framesvg
   

2. Install:

   pip install .
   

Usage

Command-Line Interface

framesvg input.gif [output.svg] [options]

• input.gif: (Required) Path to the input GIF file.
• output.svg: (Optional) Path to save the output SVG file. If omitted, the output file will have the same name as the input, but with a .svg extension.

Options:

• -f, --fps <value>: Sets the frames per second (FPS) for the animation. (Default: Uses the average FPS calculated from the input GIF's frame durations. Falls back to 10 FPS if durations are missing or invalid).

• -l, --log-level <level>: Sets the logging level. (Default: INFO). Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL, NONE. DEBUG provides detailed output for troubleshooting.

• VTracer Options: These options control the raster-to-vector conversion process performed by VTracer. Refer to the VTracer Documentation and Online Demo for detailed explanations.

  • -c, --colormode <mode>: Color mode. (Default: color). Choices: color, binary.
  • -i, --hierarchical <mode>: Hierarchy mode. (Default: stacked). Choices: stacked, cutout.
  • -m, --mode <mode>: Conversion mode. (Default: polygon). Choices: spline, polygon, none. spline creates smoother curves, but polygon often results in smaller files.
  • -s, --filter-speckle <value>: Reduces noise and small details. (Default: 4). This is a key parameter for controlling file size. Higher values = smaller files, but less detail.
  • -p, --color-precision <value>: Number of significant bits for color quantization. (Default: 8). Lower values = smaller files, but fewer colors.
  • -d, --layer-difference <value>: Controls the number of layers. (Default: 16). Higher values can reduce file size.
  • --corner-threshold <value>: Angle threshold for corner detection. (Default: 60).
  • --length-threshold <value>: Minimum path length. (Default: 4.0).
  • --max-iterations <value>: Maximum number of optimization iterations. (Default: 10).
  • --splice-threshold <value>: Angle threshold for splitting splines. (Default: 45).
  • --path-precision <value>: Number of decimal places for path coordinates. (Default: 8).

Command-Line Examples:

# Basic conversion with default settings
framesvg input.gif

# Specify output file and set FPS to 24
framesvg input.gif output.svg -f 24

# Optimize for smaller file size (less detail)
framesvg input.gif -s 8 -p 3 -d 128

# Enable debug logging
framesvg input.gif -l DEBUG

Python API

from framesvg import gif_to_animated_svg_write, gif_to_animated_svg

# Example 1: Convert and save to a file (using GIF's average FPS)
gif_to_animated_svg_write("input.gif", "output.svg", fps=30)

# Example 2: Get the SVG as a string
animated_svg_string = gif_to_animated_svg("input.gif", fps=12)
print(f"Generated SVG length: {len(animated_svg_string)}")
# ... do something with the string (e.g., save to file, display in a web app)

# Example 3: Customize VTracer options
custom_options = {
    "mode": "spline",
    "filter_speckle": 2,
}
gif_to_animated_svg_write("input.gif", "output_custom.svg", vtracer_options=custom_options)

API Reference

• gif_to_animated_svg_write(gif_path, output_svg_path, vtracer_options=None, fps=10.0, image_loader=None, vtracer_instance=None):

  • gif_path (str): Path to the input GIF file.
  • output_svg_path (str): Path to save the output SVG file.
  • vtracer_options (dict, optional): A dictionary of VTracer options. If None, uses DEFAULT_VTRACER_OPTIONS.
  • fps (float | None, optional): Frames per second. If None (default), calculates the average FPS from the input GIF. Falls back to 10.0 if calculation fails.
  • image_loader (ImageLoader, optional): Custom image loader.
  • vtracer_instance (VTracer, optional): Custom VTracer instance.
  • Raises: FileNotFoundError, NotAnimatedGifError, NoValidFramesError, DimensionError, ExtractionError, FramesvgError, IsADirectoryError.

• gif_to_animated_svg(gif_path, vtracer_options=None, fps=10.0, image_loader=None, vtracer_instance=None):

  • gif_path (str): Path to the input GIF file.
  • vtracer_options (dict, optional): A dictionary of VTracer options. If None, uses DEFAULT_VTRACER_OPTIONS.
  • fps (float | None, optional): Frames per second. If None (default), calculates the average FPS from the input GIF. Falls back to 10.0 if calculation fails.
  • image_loader (ImageLoader, optional): Custom image loader.
  • vtracer_instance (VTracer, optional): Custom VTracer instance.
  • Returns: The animated SVG as a string.
  • Raises: FileNotFoundError, NotAnimatedGifError, NoValidFramesError, DimensionError, ExtractionError, FramesvgError.

Tips for Optimizing Large File Size (> 1MB)

• Online Demo: Use this to visualize tweaking values. Experiment to find the best balance between size and quality.
• filter-speckle: This is the most impactful setting for reducing file size, especially on complex images. Increasing it removes small details.
• --mode polygon: Use the default polygon mode unless smooth curves (spline mode) are absolutely necessary. Polygon mode can significantly reduce file size by a factor of 5 or more.
• layer-difference: Increase this to reduce the number of layers.
• color-precision: Reduce the number of colors by lowering this value.

Dev

Install Hatch (Recommended)

follow this

or just

pip install hatch

Format and lint

hatch fmt

Testing

hatch test

Other Hatch Commands

hatch -h

Dev Web app

Install Vercel

Install the Vercel CLI globally:

npm install -g vercel

Running Locally

vercel dev

Setup (First Time Only): When running for the first time, you'll be prompted to configure settings. Ensure you set the "In which directory is your code located?" option to ./web.

Note: The first conversion may take a significant amount of time. This is because the serverless functions need to be built. Subsequent conversions will be faster.

Deploy to Vercel

vercel deploy

Contributing

Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.