Video to Spritesheet

Arxk · December 8, 2024, 7:47am

Creating and uploading sprite sheets made easy!

What Is This?

Transform your video files into dynamic sprite sheets with ease! Video to Spritesheet supports a variety of formats including .mp4, .mov, .avi, .mkv, .flv, and .wmv. It has out of the box support for:

Alpha Channels: Convert videos with transparent backgrounds, preserving the transparency in the created sprite sheets.
Automated Asset Uploading: Offers the ability to upload all created sprite sheets to Roblox, automatically ordering them in a .luau file for seamless integration into your game.

Currently, VideoFrame has no support for Alpha Channels, only upload 3 videos every 30 days, cost 2,000 R$ per upload and still has a fair amount of bugs-- While VideoFrame is an awesome feature, it remains very limited and cannot be used for more advanced videos like transparent background animations seen in examples below.

Examples

videos are recorded with gyazo, some examples are lower in quality than original

Installation

You need:

Node.js (below version 21) (Node.js — Download Node.js®)

Setup

Clone the repository to where you want.
Run npm install to install the dependencies when you are in the terminal for your project.
Place your video(s) in the input_videos folder (supports: .mp4, .mov, .avi, .mkv, .flv, and .wmv).
If you plan on uploading to Roblox, make sure you go into .env and setup your Open Cloud API_KEY and USER_ID or GROUP_ID (wherever you wish to upload from).

image681×108 12.7 KB

It is important that you create a .env file (rename .env.example to .env) with these variables if you want to upload to Roblox automatically.

Usage

When you run the script, you’ll be followed with prompts which allow you to configure how you want to process your video with the desired sprite sizes, sheet size, frame rate, threads, input videos directory, etc.

Run npm start and follow the prompts.

Prompt Questions:

Input Directory: The folder in which your videos are. You can have as many videos as you want. (Defaults at input_videos)
Videos to Process: If you have more than one video in the folder, you can specify a specific video to process, or all.
Frame Size: The size of the sprite frame. (Defaults at 1024x1024)
Sheet Size: The size of the entire sprite sheet. (Defaults at 4096x4096)
Use Video Frame Rate: If you enable this, it will automatically determine the frame rate of the video and use that for processing, if not you can specify your own frame rate.
Frame Rate: The desired frame rate of your sprite sheet. (Defaults at 25)
Threads: The amount of threads that will be used for frame extraction on the video, it will default at the cores of your PC, but if you want to specify lower to save on resources, then feel free (it will be slower).

Once it’s done processing, you’ll see a folder in sprite_results for details on your sprite sheet (time stamped), and you’ll see a .luau file in uploaded_sprites if you uploaded the sprite sheets.

Extras

There’s an extra script provided which allows you to specify a folder and upload all of the sprite sheets inside to Roblox whilst keeping the sequence and creating a .luau file with the organized sprite sheets.

Run npm run uploadSpritesToRoblox and follow the prompts.

Prompt Questions:

Input Directory: The folder in which your videos are. You can have as many videos as you want. (Defaults at input_sheets)

(only if no GROUP_ID or USER_ID provided):

Upload Type (Group or User): Specify a type so it knows where to upload to.
Group ID: Specify a Group ID if that’s where you want to upload.
User ID: Specify a User ID if that’s where you want to upload.

When it’s finished, it’ll create a timestamped .luau file in a folder uploaded_sprites.

Uploading to Roblox can take a bit. Usually around 8-10 minutes for ~80 sprite sheets.

Issues & Contributing

If you run into problems, submit an issue within the repository & if you want to contribute, submit a pull request.

- Made with by @blox_darkrai and @Arxk

iProjectionix · January 18, 2025, 12:11am

I tried setting this up yesterday, however I can’t seem to figure out how to get started. What do I download? Where does that go? I have so many questions, I am pretty good at figuring stuff out, but I was completely stumped. Is there any video tutorial or a better explanation anywhere?

Arxk · January 18, 2025, 6:34pm

A video tutorial will be done eventually. Have you followed the instructions in the thread?

Clone the GitHub repository to your PC (GitHub - verticalfx/video-to-spritesheet)
Open a terminal inside the cloned directory
Run npm install (or whatever package manager you have)
Setup config
Run npm start to simply start the program

Askofep · February 1, 2025, 5:17am

It errors

Arxk · February 1, 2025, 6:32pm

Can you provide more details or the output?

Askofep · February 1, 2025, 8:00pm

> spritesheet1@1.0.0 start
> tsx index.ts

file:///home/ashton/video-to-spritesheet/node_modules/zod/lib/index.mjs:587
                const error = new ZodError(ctx.common.issues);
                              ^

ZodError: [
  {
    "code": "invalid_type",
    "expected": "string",
    "received": "undefined",
    "path": [
      "API_KEY"
    ],
    "message": "Required"
  }
]
    at get error (file:///home/ashton/video-to-spritesheet/node_modules/zod/lib/index.mjs:587:31)
    at ZodObject.parse (file:///home/ashton/video-to-spritesheet/node_modules/zod/lib/index.mjs:692:22)
    at <anonymous> (/home/ashton/video-to-spritesheet/env.ts:13:23)
    at ModuleJob.run (node:internal/modules/esm/module_job:271:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:547:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5) {
  issues: [
    {
      code: 'invalid_type',
      expected: 'string',
      received: 'undefined',
      path: [ 'API_KEY' ],
      message: 'Required'
    }
  ],
  addIssue: [Function (anonymous)],
  addIssues: [Function (anonymous)],
  errors: [
    {
      code: 'invalid_type',
      expected: 'string',
      received: 'undefined',
      path: [ 'API_KEY' ],
      message: 'Required'
    }
  ]
}

Node.js v22.12.0

Askofep · February 1, 2025, 8:01pm

need support for new versions

Arxk · February 2, 2025, 3:30am

Sorry about this, it looks like it forces you to have an API_KEY which should not be happening. You should only be required to provide an API_KEY if you are uploading sheets to Roblox.

This is now fixed.

hwoagh_a · February 18, 2025, 5:29am

could you make a video tutorial on this?

oomer1 · May 2, 2025, 8:49pm

I get this whenever I try converting it to a spritesheet,

Arxk · May 3, 2025, 4:55am

Is your input_videos folder (do you have one?) in the same place that you are executing it from? The errors indicates that the input path is not valid

Vedden · August 5, 2025, 12:18am

Is there going to be a video tutorial for this yet? I’m not getting an input_videos folder created when I run npm install.

WillysInPain · August 6, 2025, 11:49am

[deprecated cause new fixes has been added]

Arxk · August 6, 2025, 4:05pm

You will want to just create an input_videos folder. I have updated the repository to automatically include a folder for the videos. Make sure to delete the current video in there as it’s just a placeholder.

I’ve also fixed a couple issues.

Arxk · August 6, 2025, 4:13pm

Thanks. You could PR bug fixes if you want, it looks like you left the fork network though…

Also, the IDs in the luau file are accurate to my knowledge?

I could not see any noticeable diffs in the repositories other than axios vs Axios. You also turned .env into a config file? I’m not sure why you would do that as the API_KEY is a sensitive value… There’s not really any reason for the env variables to be abstracted into a config.ts file.

WillysInPain · August 6, 2025, 6:27pm

mb! i was new to github collaboration and just used the tool for myself at the time. gonna deprecate it, was a very temporary and not production ready fix that solved the problem for me since there hasnt been an update on it in a while.

i’ve tested your new fix, the conversion works perfectly but you forgot to include “.gif” files in this function. also there seems to be an issue with the API keys when uploading sprites, i tried issuing a PR but Im not a collaborator

(the API key is in fact set in examples.env)

Arxk · August 6, 2025, 7:29pm

No worries! You can just fork the repository, pull it on your local machine, make changes, publish them and then submit them as a PR.

If you don’t want to, just open an issue (I’ve enabled issues).

I have now included webm and gif. I also made that API_KEY error a bit more intuitive, you should be setting API_KEY in your .env, it shouldn’t be called ROBLOX_API_KEY.

WillysInPain · August 6, 2025, 10:14pm

I think ive figured out the uploading issue now. It seems ive missed a step from the tutorial, changing the filename from “.env.example” to “.env”
Feels like such a stupid mistake, but it works properly now, thanks for the great tool!