https://github.com/romelium/framesvg

A web app, command-line tool, and Python library to convert animated GIFs into animated SVGs. framesvg offers automatic playback, scalability, and customizable VTracer options for optimal vectorization.
https://github.com/romelium/framesvg

animated-svg cli command-line command-line-tool converter gif gif-animation gifs image-converter python python-library raster-to-vector svg svg-animations vtracer web web-graphics webapp website

Last synced: 3 months ago
JSON representation

A web app, command-line tool, and Python library to convert animated GIFs into animated SVGs. framesvg offers automatic playback, scalability, and customizable VTracer options for optimal vectorization.

• Host: GitHub
• URL: https://github.com/romelium/framesvg
• Owner: Romelium
• License: mit
• Created: 2025-02-06T19:32:41.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2025-04-13T13:13:18.000Z (6 months ago)
• Last Synced: 2025-06-28T18:18:28.150Z (3 months ago)
• Topics: animated-svg, cli, command-line, command-line-tool, converter, gif, gif-animation, gifs, image-converter, python, python-library, raster-to-vector, svg, svg-animations, vtracer, web, web-graphics, webapp, website
• Language: Python
• Homepage: https://framesvg.romelium.cc
• Size: 6.32 MB
• Stars: 9
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  





  Convert animated GIFs to animated SVGs.





  

  

  

  







`framesvg` is a [web app](https://framesvg.romelium.cc), command-line tool, and Python library that converts animated GIFs into animated SVGs. It leverages the power of [VTracer](https://www.visioncortex.org/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](https://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](https://framesvg.romelium.cc/examples.html).

## Examples

There is a dedicated and more better example page [here](https://framesvg.romelium.cc/examples.html)

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.

```bash

pipx install framesvg

```

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

```bash

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:

```bash

pip install framesvg

```

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

### From Source

1. **Clone the repository:**

    ```bash

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

    cd framesvg

    ```

2. **Install:**

    ```bash

    pip install .

    ```

## Usage

### Command-Line Interface

```bash

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 `:**  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 `:**  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](https://www.visioncortex.org/vtracer-docs/) and [Online Demo](https://www.visioncortex.org/vtracer/) for detailed explanations.

  * `-c`, `--colormode `:  Color mode. (Default: `color`).  Choices: `color`, `binary`.

  * `-i`, `--hierarchical `:  Hierarchy mode. (Default: `stacked`). Choices: `stacked`, `cutout`.

  * `-m`, `--mode `:  Conversion mode. (Default: `polygon`). Choices: `spline`, `polygon`, `none`.  `spline` creates smoother curves, but `polygon` often results in smaller files.

  * `-s`, `--filter-speckle `:  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 `:  Number of significant bits for color quantization. (Default: 8). Lower values = smaller files, but fewer colors.

  * `-d`, `--layer-difference `:  Controls the number of layers. (Default: 16).  Higher values can reduce file size.

  * `--corner-threshold `:  Angle threshold for corner detection. (Default: 60).

  * `--length-threshold `:  Minimum path length. (Default: 4.0).

  * `--max-iterations `:  Maximum number of optimization iterations. (Default: 10).

  * `--splice-threshold `:  Angle threshold for splitting splines. (Default: 45).

  * `--path-precision `:  Number of decimal places for path coordinates. (Default: 8).

**Command-Line Examples:**

```bash

# 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

```python

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](https://www.visioncortex.org/vtracer/):**  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](https://hatch.pypa.io/latest/install)

or just

```bash

pip install hatch

```

### Format and lint

```bash

hatch fmt

```

### Testing

```bash

hatch test

```

### Other Hatch Commands

```bash

hatch -h

```

## Dev Web app

### Install Vercel

Install the Vercel CLI globally:

```bash

npm install -g vercel

```

### Running Locally

```bash

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

```bash

vercel deploy

```

## Contributing

Contributions are welcome!  Please submit pull requests or open issues on the [GitHub repository](https://github.com/romelium/framesvg).