Projects

A Plinken project contains everything for a production: tracks, regions, assets, sync settings, Lua scripts, notes, and module state. Projects are stored as .plin files (JSON) alongside a directory of media assets.

Project Manager

Open the Project Manager to browse, create, and open projects.

Action	Shortcut	Command ID
New Project	⌘N	`projects:show-new`

The Project Manager shows a list of recent projects with metadata (name, BPM, key, sample rate, template, last opened date). Click a project to open it.

Recent Projects

Plinken maintains a database of recently created and opened projects. Each entry stores:

Field	Description
Name	Project display name
Path	Absolute path to the project directory
BPM	Tempo at creation
Key	Key signature
Sample Rate	Audio sample rate (e.g., 48000 Hz)
Template	Template used to create the project
Space ID	Linked collaborative Space (if any)

Creating a Project

Press ⌘N to open the New Project dialog. Configure:

Setting	Default	Description
Name	”My Project”	Project name (becomes the directory name)
BPM	120.0	Initial tempo
Key Signature	C major	Root key for the timeline
Sample Rate	48000	Audio sample rate in Hz
Template	empty	Starting template

Templates

Template	Description
Empty	Blank project with no tracks
Audio	Pre-configured with audio tracks and sample files
Remote	Downloaded from the Plinken template library (R2 storage)

Remote templates are defined in resources.json and downloaded as ZIP archives on first use. They can include pre-built tracks, audio files, and settings.

Directory Structure

When you create a project, Plinken creates the project directory and all standard subdirectories:

~/.plinken/projects/{name}/
├── {name}.plin          # Project file
├── audio/               # Audio assets
├── video/               # Video assets
├── images/              # Image assets
├── action/              # Lua scripts
├── face/                # Face animation data
├── scripts/             # Fountain screenplays
├── lyrics/              # Lyrics
├── glb/                 # 3D models (glTF)
├── usd/                 # USD scene data
├── splat/               # Gaussian splats
├── editor3d/            # 3D editor state
├── comfyui/             # ComfyUI workflows
├── volumeFX/            # Volume effects
└── logs/                # Session logs

Opening a Project

Open an existing project by:

Selecting it from the Project Manager recent list
Opening a .plin file directly (double-click in Finder)

Plinken automatically reopens the last project on launch. The last project name and path are stored in the settings database.

Version Compatibility

Projects include a format version number. Plinken checks this on load:

If the version is below the minimum loadable version, the project is rejected with an error
If the version is current or recent, the project loads normally

This prevents data loss from opening projects in incompatible versions.

Saving

When you make changes, the project is automatically marked as dirty. Plinken queues saves to avoid interrupting your workflow.

Project File Format

The .plin file is JSON containing:

Section	Description
meta	Name, author, timestamps, format version
sync_settings	Sample rate, tempo map (BPM + time signatures at tick positions), frame rate
timeline	Tracks, regions, root key, snap mode
modules	All module state (transport, mixer, video, etc.)
assets	Asset index (name, URI, type, audio metadata, MD5 hash)

Sync Settings

The sync settings define the project’s timing foundation:

Property	Description
sample_rate	Audio sample rate (44100, 48000, 88200, 96000)
tempo_map	Array of `TempoEntry` objects defining BPM and time signature changes
frame_rate	Video frame rate (24, 25, 29.97 NDF, 29.97 DF, 30 fps)

Each tempo map entry contains:

Field	Description
tick	Position in PPQ ticks where this tempo begins
bpm	Beats per minute
time_signature_num	Numerator (e.g., 4 for 4/4)
time_signature_den	Denominator (e.g., 4 for 4/4)

Cloud Sync

Sync project assets to Cloudflare R2 cloud storage for backup and multi-device access.

Action	Shortcut	Command ID
Sync to Cloud	⌘⇧Y	`assets:syncToR2`
Sync from Cloud	—	`assets:syncFromR2`

Assets are stored using content-addressed storage: each file is keyed by its MD5 hash. This means:

Identical files are never uploaded twice
Files are stored at {spaceId}/assets/{md5}.{ext}
Downloading checks local MD5 against remote to skip up-to-date files

Spaces

Spaces are collaborative workspaces for real-time multi-user sessions. When a project is linked to a Space, collaborators can:

See each other’s cursors and selections
Share notes (synced via Y.js CRDTs)
Join voice/video calls
Stream and watch together

Create or join a Space from the Space menu in the menu bar.

Lua API

Access project information from Lua scripts:

local ctx = pl.get_context()
pl.log("Project: " .. tostring(ctx.projectName))
pl.log("Space: " .. tostring(ctx.space and ctx.space.title or "none"))

-- Create a new project
pl.cmd("projects:show-new")