Video Player

The node sits on Apple's native media stack (AVFoundation with hardware decode). One node owns one video file; many nodes play many videos simultaneously. Frames render to a texture exactly like Camera Input, aspect-fitted against the full viewport rectangle (the viewport-fit convention), so Width and Height come out ready for a Canvas without manual math, with premultiplied alpha and anti-aliased edges.

Transport semantics. Time Mode chooses between two worlds:

• Transport (0) — normal playback. Play runs or pauses, Speed sets the rate, In Point and Out Point (both 0–1 fractions of the full duration) mark the region that actually plays, and Loop Mode decides what happens when the Out point is reached.
• Scrub (1) — playback stops and the Scrub port becomes the timeline: 0 is the very start, 1 the very end, and any change beyond a tiny tolerance seeks immediately. Wire an LFO, a fader or an EEG channel to Scrub and you are scratching video.

Loop modes (Transport only):

Events. Restart is edge-triggered: a rising edge (false → true) seeks back to the In point and clears any hold or fade state — hold it high and nothing repeats, which is what makes it safe to drive from a beat detector. Finished is a one-frame pulse fired every time the Out point is reached, in every loop mode, per Grafit's event-logic conventions — including on each loop wrap, so it doubles as a cycle tick.

Speed is a varispeed rate — tape-style, so pitch follows speed on the audio track. Extreme ranges are supported (roughly 1/32× to 32×), and negative direction is handled by Ping-Pong rather than by a negative value.

Audio. The video's audio track is captured into Grafit's shared audio currency: the Audio output plugs straight into Audio FFT / Audio Analysis, exactly like Audio Input, and into the audio filter family. Volume and Mute control what you hear through the system output without touching what the analysis sees.

File handling. Browsing for a file in the inspector stores a security-scoped bookmark with the project, so the file stays accessible after quitting and relaunching the app — essential under App Store sandboxing. A file picked in the inspector takes effect immediately, without re-enabling the node. Cable-driven paths take priority over the stored one; if nothing resolves, the node's own stored value is used, which is what keeps a disabled player from tearing down and rebuilding its session every frame.

Outputs: Image (the video texture), Audio (structure — the live audio ring for FFT / Analysis / filters), Width and Height (viewport-fit dimensions), Time (current position in seconds), Progress (0–1 across the full duration), Duration (seconds), Playing (Bool, true whenever the rate is non-zero), Finished (a one-frame pulse at the Out point) and Info (structure with file/codec details).

• Basic playback — Video Player Image → Canvas: the file fills the viewport at the correct aspect ratio; set Loop Mode to Loop and forget about it.
• Scratch video with an LFO — set Time Mode to Scrub, LFO (triangle, 0.2 Hz) → Scrub: the clip rocks back and forth in perfect sync with the oscillator, no transport involved.
• Beat-locked stinger — Loop Mode = Once — Hold Last Frame, Audio Beat Detection Kick → Restart: the clip retriggers on every kick and freezes on its last frame between hits.
• Playlist switching — a String Switch feeding File, driven by a Counter on the Finished pulse: each clip finishing advances the playlist automatically.
• Video as an audio source — Audio → Audio FFT → Audio Spectrum → Canvas: the soundtrack of the clip drives a spectrum visual with millisecond analysis cadence, identical to the mic path.
• Region loop for a VJ set — set In Point 0.35 and Out Point 0.55, Loop Mode Loop: only the money shot loops, and Finished ticks once per cycle for downstream events.
• Slow fade-out ending — Loop Mode = Once — Fade to Black with Fade Duration 3: the clip darkens in the shader while keeping alpha, so it dissolves cleanly over whatever Canvas layers sit beneath.

• Always Browse for the file at least once, even if you plan to drive File by cable: the browse creates the security-scoped bookmark that keeps the file readable after a relaunch. A bare path string from a cable has no bookmark of its own.
• Restart is a rising edge, not a level — a permanently true cable retriggers exactly once. Use a Do Once or a 1-frame pulse source to retrigger repeatedly.
• Finished is a one-frame pulse and fires on every loop wrap, not only at the end of a Once mode. It is the cleanest per-cycle tick available from a video.
• Ping-Pong depends on the codec: files that cannot play in reverse silently fall back to a plain loop. Re-encode to an editing-friendly codec (ProRes, DNxHD) if reverse matters.
• In Point and Out Point are fractions of the full file duration, and Progress is likewise measured against the full duration — not against the In/Out region.
• In Scrub mode Play, Speed, Loop Mode and Restart are inert; the inspector hides them so the panel matches what actually does something.
• Audio and video routing are separate concerns: analysis on the Audio output stays live regardless of Volume and Mute, so you can drive visuals from a silent clip.