Hello Voxel World: Your First 3D Video in Python with spatialstudio

Build and preview an interactive voxel animation in under 30 lines of code.

Your first 3D video in Python with spatialstudio

Interactive 3D video looks like magic until you see how little code it takes.

Here’s how to make your own 3D video in Python using open-source tools, just like this Vaporwave Music Visualizer by @frozein

In this post you will:

• install the open‑source spatialstudio package

• generate a tiny voxel movie in under thirty lines

• preview the result in your browser

• learn how to take full control of every voxel

You can follow along locally or run everything in a ready‑to‑go Google Colab notebook.

What’s a voxel?

Think of a voxel as a 3D pixel. A pixel has position (x, y) and color; a voxel adds the z coordinate, giving you a tiny colored cube in space. A voxel grid is just a 3‑dimensional image made of those cubes. In this tutorial you will animate voxels, encode them into a .splv file and view the result in a browser.

.splv plays the same role for 3D video that .mp4 plays for traditional 2D video. Each frame is stored as a compact voxel volume (.vv), similar to how video frames are stored in an .mp4.

With high enough resolution, voxel grids can even represent photorealistic humans.

Basketball by @al

Tutorial

---

1. Install the toolkit

pip install spatialstudio

That is the only dependency.

---

2. Hello‑world voxel video

Copy the snippet below into hello_world_splv.py. It builds a 128 × 128 × 128 scene, animates three colored cubes, then writes a .splv file.

from spatialstudio import splv

# scene size
width, height, depth = 128, 128, 128

# encoder
encoder = splv.Encoder(
    width,
    height,
    depth,
    framerate = 30.0,
    outputPath = "my_spatial.splv"
)

# 100 frames of animation
for i in range(100):
    frame = splv.Frame(width, height, depth)

    # stretching red cube
    frame.fill(xMin = 1,  yMin = 2,  zMin = 3,
               xMax = 10 + i, yMax = 25, zMax = 35,
               voxel = (255, 0, 0))

    # sliding green cube
    frame.fill(xMin = 40, yMin = 10 + i, zMin = 20,
               xMax = 70, yMax = 20 + i, zMax = 50,
               voxel = (0, 255, 0))

    # growing blue cube
    frame.fill(xMin = 127 - i, yMin = 127 - i, zMin = 127 - i,
               xMax = 127, yMax = 127, zMax = 127,
               voxel = (0, 0, 255))

    encoder.encode(frame)

encoder.finish()
print("done, file saved to my_spatial.splv")

Run it. A 100‑frame voxel video appears in the working folder.

---

3. Preview the result

Drag my_spatial.splv onto the free online viewer at
https://www.splats.tv/upload

The player lets you scrub the timeline, orbit the camera, and confirm that everything encoded correctly.

You should see something that looks like this

---

4. How the code works

• The Encoder gathers frames and writes them into a .splv file.

• Frame is an empty 3D grid for a single moment in time.

• fill paints a rectangular block of voxels in one call.

• Once a frame is painted, encode adds it to the stream.

• finish closes the file and flushes all data to disk.

---

5. Maximum control with set_voxel

The fill function is great for getting started, but to use the full power of `spatialstudio` you will need voxel level precision.

The tiny demo below writes a single red voxel that marches along the scene diagonal.

from spatialstudio import splv

# scene setup
W, H, D = 16, 16, 16
encoder = splv.Encoder(W, H, D, framerate=4.0, outputPath="moving_dot.splv")

# animate a single red voxel from one corner to the opposite
for t in range(W):                      # 2‑second clip at 30 fps
    f = splv.Frame(W, H, D)
    x = y = z = t                       # moves along the main diagonal
    f.set_voxel(x, y, z, (255, 0, 0))   # place the dot
    encoder.encode(f)

encoder.finish()
print("done, file saved to moving_dot.splv — upload it to https://www.splats.tv/upload to view")

Preview moving_dot.splv exactly as before.

---

6. Next steps

• Design your own animations by choosing voxel positions frame by frame

• Adjust resolution and framerate to balance visual quality and file size

• Import scenes from Unity or Blender using the live‑streaming API

The field is wide open and creating interactive 3D video has never been easier

Share what you build in the #creations channel in our discord and our reddit