AC-Pack Tape Recording Guide #

Overview #

ac-pack can package OBJKTs using pre-recorded tape archives from the aesthetic.computer client. This method gives you full control over the animation recording and generates multiple optimized GIF covers automatically.

Quick Start #

Option 1: Interactive Mode (Recommended) #

node objkt/ac-pack.mjs piece-name

The tool will ask if you want to record a tape first and guide you through the process.

Option 2: Direct Tape Usage #

If you already have a tape file:

node objkt/ac-pack.mjs piece-name --tape ./path/to/tape.zip --tape-start 50

Recording a Tape #

In the aesthetic.computer client: #

1. Navigate to your piece (e.g., aesthetic.computer/piece-name)
2. Press r to start recording
3. Let your piece run and animate
4. Press r again to stop recording
5. The tape will be saved as a ZIP file with timestamp (e.g., piece-name-2025.10.08.14.30.00.123.zip)
6. Download the tape ZIP from your browser's download folder

Tape Contents #

The ZIP contains:

• PNG frames: Sequential frames of your animation (e.g., frame000000.png, frame000001.png, ...)
• timing.json: Frame timing data (filename, duration, timestamp for each frame)
• metadata.json: Recording metadata (dimensions, scale, duration)
• soundtrack.wav: Audio recording (if any)

AC-Pack Options #

--tape <path> #

Path to your tape ZIP file. When provided, ac-pack will:

• Skip the orchestrator/renderer completely
• Extract frames from the tape
• Generate all covers from the recorded animation

Example:

node objkt/ac-pack.mjs $4bb --tape ./\$4bb-2025.10.08.14.30.00.123.zip

--tape-start <percentage> #

Start the cover animation from a specific percentage of the tape (0-100). Useful for skipping black/loading frames at the beginning.

Example:

node objkt/ac-pack.mjs $4bb --tape ./tape.zip --tape-start 50

This starts the animation from the middle frame (50% through the tape).

Generated Outputs #

When using --tape, ac-pack automatically generates four optimized GIF versions:

1. Main Cover (-cover.gif) #

• Size: 512x512 pixels
• Frame Rate: 50fps (constant, matches tape)
• Colors: 128 colors with Bayer dithering
• Use: Primary OBJKT cover
• Typical Size: ~46MB (full quality, all frames from tape-start to end)

2. Twitter/X Cover (-x.gif) #

• Size: 800x800 pixels
• Frame Rate: 24fps
• Duration: 11 seconds (264 frames)
• Colors: 16 colors with Bayer dithering (scale 5)
• Use: Social media sharing (Twitter/X has 15MB limit)
• Typical Size: ~14.5MB (under 15MB limit)

3. objkt.com Cover (-objkt.gif) #

• Size: 600x600 pixels
• Frame Rate: 4fps (0.25 seconds per frame - slow slideshow)
• Frames: 6 frames (evenly sampled from tape)
• Colors: 256 colors (full palette, no reduction!)
• Use: Marketplace listing preview
• Typical Size: ~1.6MB (well under 2MB objkt.com limit)
• Style: Contemplative slideshow with rich, full-color quality

4. Icon Set (icon.gif + PNGs) #

• Animated GIF: 128x128 pixels, 64 colors, all frames
• Static PNGs: 128x128, 256x256, 512x512 (from final frame)
• Use: Favicon, app icons, thumbnails
• Typical Size: ~4.2MB (animated)

Example Workflow #

Complete tape-based packaging: #

# 1. Record your piece in the browser (press 'r' twice)
# 2. Download the tape ZIP
# 3. Package with tape, starting from 50%
node objkt/ac-pack.mjs mypiece --tape ./mypiece-2025.10.08.14.30.00.123.zip --tape-start 50

# Output files created:
# - @author-mypiece-timestamp-cover.gif     (46MB - main)
# - @author-mypiece-timestamp-x.gif         (14.5MB - Twitter)
# - @author-mypiece-timestamp-objkt.gif     (1.6MB - objkt.com)
# - icon/128x128/mypiece.gif                (4.2MB - animated icon)
# - icon/128x128/mypiece.png                (static icon)
# - icon/256x256/mypiece.png                (static icon)
# - icon/512x512/mypiece.png                (static icon)
# - @author-mypiece-timestamp.zip           (50.9MB - complete package)

Tips #

Finding the Right Start Percentage #

• Use --tape-start 0 for the full recording
• Use --tape-start 25 to skip the first quarter (if loading/black frames)
• Use --tape-start 50 to start from the middle
• Experiment to find the best starting point for your piece

File Size Optimization #

All three GIF covers use different optimization strategies:

• Main cover: Balanced quality (128 colors) for Teia
• Twitter cover: Optimized for 15MB social media limit (16 colors, shorter duration)
• objkt.com cover: Slideshow preview (6 frames, full colors, slow pace)

When to Use Tape vs. Orchestrator #

Use tape when:

• You want precise control over the animation
• Your piece has complex timing or interactions
• You want to capture a specific run/performance
• You need consistent output across all covers

Use orchestrator (no --tape) when:

• Your piece is simple and deterministic
• You want quick automated rendering
• You don't need precise frame control

Troubleshooting #

"Tape file not found" #

• Check the file path is correct
• Use relative or absolute paths
• Escape special characters in filenames (e.g., \$ for $ in bash)

Cover is too large #

• Increase --tape-start to use fewer frames
• The tool will warn if covers exceed their target limits
• Twitter cover must be under 15MB
• objkt.com cover should be under 2MB

Colors look wrong #

• Main cover uses 128 colors (high quality)
• Twitter cover uses 16 colors (optimized for size)
• objkt.com cover uses 256 colors (full palette slideshow)
• This is intentional for different use cases

File Size Targets #

Cover Type	Resolution	Target Size	Purpose
Main	512x512	~46MB	Teia primary cover (full quality)
Twitter/X	800x800	<15MB	Social sharing (X platform limit)
objkt.com	600x600	<2MB	Marketplace listing preview
Icon	128x128	~4MB	Favicon/thumbnails

Notes #

• All GIF outputs are created automatically when using --tape
• The objkt.com cover is a slow slideshow (6 frames, 0.25s each) with full color palette
• The Twitter cover is optimized for social media (24fps, 11 seconds, under 15MB)
• The main cover includes all frames from tape-start to end
• Icons use the final frame to show the most progressed state
• Soundtrack is noted but not bundled (keeps package size manageable)