Media Players

Arkestra has three media layer types that let you feed video, still images, and GIFs into your track chain: Video Player, Image Player, and GIF Player. Each type supports a playlist — a queue of sources you can switch between manually or automate.

---

Video Player

The Video Player renders video frames as a texture into the track chain. It supports two source types: local files and Pexels stock videos. The Video, Image, and GIF categories in Add Content each have two tabs — the online library and Local — and remember which one you used last.

Sources

Source	How to add
Local file	In Add Content → Video, switch to the Local tab and pick a file. You can also click the + slot in the playlist bar, or drag a file from the Local Media browser
Pexels	In Add Content → Video, stay on the Pexels tab, search or browse, then click a result to add it

Supported formats include standard video formats (.mp4, .mov, .avi, etc.) as well as HAP-encoded files for GPU-accelerated playback.

Playback controls

Parameter	Description
Play/Stop	Toggleable trigger — true = playing, false = paused. Mappable to MIDI or keyboard.
Muted	When on, video audio is silenced. On by default.
Reversed	Plays the video backwards.
Speed	Playback rate multiplier, 0–4x (1x = normal). Mappable and modulatable, so an LFO, envelope, or MIDI CC can ramp playback speed. 0 freezes the video.
Play Mode	Loop — restarts when the clip ends. One Shot + Hold — pauses on the last frame when done. One Shot + Black — outputs black when the clip ends.

Sync mode

When Sync is enabled, the video position is driven by a mappable Progress parameter (0–1) instead of free-running playback. This lets you scrub video with an LFO, sequencer, MIDI CC, or audio input.

• Progress Offset shifts the start point of synced playback.
• Clip Start and Clip Length trim the active region of the clip to a sub-range (0–1). For example, Clip Start = 0.25 + Clip Length = 0.5 plays the middle half of the video.

Timeline Sync is a sub-mode of Sync that drives the video position directly from the project timeline playhead, so the video locks to bar position.

Trim and Crop

Right-click any video clip in the playlist to open the Edit modal. It provides:

• Live preview player with looping playback
• Trim handles — drag the in and out points to define the active clip window
• Crop overlay — define a rectangular crop region
• Start / Length controls — fine-tune the playback window numerically within the trimmed range

---

Image Player

The Image Player renders a still image as a texture into the track chain.

Sources

Source	How to add
Local file	In Add Content → Image, switch to the Local tab and pick a file. You can also click Add Image in the inspector, or drag files from the Local Media browser
Unsplash	In Add Content → Image, stay on the Unsplash tab, search or browse editorial photos, then click a result

Supported image formats: PNG, JPEG, TIFF, BMP, HEIC.

Unsplash images are loaded directly from URL and conform to Unsplash attribution guidelines — the photographer’s name and a link to their profile are preserved in the item metadata.

---

GIF Player

The GIF Player decodes and plays back animated GIFs frame by frame using CPU-decoded frames uploaded to the GPU each frame.

Sources

Source	How to add
Local GIF file	In Add Content → GIF, switch to the Local tab and pick a file. You can also click Add GIF in the inspector, or use the Local Media browser
Giphy	In Add Content → GIF, stay on the Giphy tab, search or browse trending GIFs, then click a result

Playback parameters

Parameter	Description
Speed	Frame advance rate per render tick. Default 0.25. Mappable.
Time	When Time Mode is on, the GIF frame is driven by a 0–1 value instead of the speed counter — great for scrubbing with an LFO or audio input.

Decoded frames are cached in memory so switching between playlist items that have already been loaded does not re-download or re-decode them.

---

Capture Device

The Capture device (add it from the External Sources browser — red record.circle icon, labelled Capturer) records the output of any track straight to disk. It also plays back its own video playlist like a Video Player.

Control	What it does
Source	Which track to record from (or the chain’s input texture)
Capture	Saves a single still frame (.png) from the source track
Record	Toggle — records live video from the source track until you stop

Captures land in a dedicated Captures folder named after your project. Stills are named Arkestra Capture - <timestamp>.png; finished video recordings are added to the device’s playlist automatically so you can play them back immediately.

The device includes the standard video playback controls — playlist navigation, autoplay, crossfade, Muted, and a Manual Playback toggle so you can drive captured files on their own timeline rather than a progress source.

---

The Playlist

Every media player — video, image, and GIF — has a playlist: an ordered list of sources. Only one item is active at a time; the rest are queued and ready to switch to instantly.

Adding items

• Tap the + slot at the end of the thumbnail bar in the inspector. The popover has two tabs: the online library (Pexels, Unsplash, or Giphy) and Local. It remembers which tab you used last, plus your last search and pinned-only filter, separately for video, image, and GIF. Turn off Close after add at the bottom to keep the popover open and add several items in a row. In either tab, press ↑ / ↓ to step through the list while you type a search, and Return to add the highlighted item.
• Use the Pexels, Giphy, Unsplash, or Local Media browsers to add items to the active playlist directly without creating a new track.
• Select multiple files in the Local Media browser and tap Add N to Playlist to batch-add them.
• Click Add All on a folder header (Local tab) or a collection header (pinned Pexels or Unsplash items) to add the whole group at once. In the playlist popover the items are appended to that playlist. In Add Content they become one new Video or Image player, named after the folder or collection, with every item in its playlist.

Activating an item

• Click a thumbnail in the bar to inspect it (blue border).
• Double-click a thumbnail, or click the play button that appears on hover, to activate it (it becomes the live source).
• The active item is marked with a ▶ icon in the top-right corner of its thumbnail.

Reordering

Drag thumbnails left or right to reorder the playlist. The active item selection is preserved after a reorder.

Replacing an item

Right-click a thumbnail and choose Replace… to swap the source at that position while keeping its playlist slot, MIDI mappings, and per-item trigger intact. For Pexels videos you can also choose Show in Pexels to open the original clip in a browser.

Deleting an item

Right-click a thumbnail and choose Delete, or select the item in the inspector list and press Delete or Backspace.

To empty the whole playlist, right-click any thumbnail and choose Delete All (or Remove All in the inspector list). The track goes blank until you add new media.

---

Playlist navigation

Three navigation controls appear below the thumbnail bar, each independently mappable to MIDI, keyboard, LFO, or any other source:

Control	Behavior
← Prev	Moves to the previous item (wraps around).
Shuffle	Jumps to a random item (never repeats the current one).
Next →	Moves to the next item (wraps around).

Per-item triggers

Each playlist item has its own trigger — a BoolValue that activates that specific item on a rising edge. Right-click a thumbnail and choose Map To…, MIDI Learn, or Keyboard from the context menu to assign a trigger to that slot. This lets you map individual keys or MIDI pads to specific clips.

Autoplay

The Autoplay dropdown advances the playlist automatically. Options:

Setting	Behavior
No autoplay	Manual only — no automatic advancement.
Fader	Advances to the next item when the track fader reaches zero.
32 Bars … 1/16	Advances on a musical time division synced to tempo via Ableton Link or the project clock.

Time-based autoplay uses the same bar/beat clock as LFOs and sequencers, so the playlist stays locked to the groove.

Crossfade transitions

Video, image, GIF, and text playlists can crossfade between items instead of cutting hard. Enable the Crossfade toggle in the inspector, then shape the transition:

Control	What it does
Crossfade	Toggles crossfade on/off. Mappable.
Duration	How long the blend takes (0.01 – 5.0 s). Double-click to reset to 0.5 s.
Blend Mode	The compositing operation used during the transition. Mappable.
Curve	Easing curve — Linear, Ease In/Out, Cubic In/Out, Expo In/Out, Logarithmic, Exponential, and more.

The previous item stays live during the transition so the blend uses current frames from both sources, and is released once the fade completes.

---

Online media sources

Pexels (videos)

Pexels provides royalty-free stock video. Open the Pexels tab in the browser to browse or search.

• Orientation filter — Auto-selected based on your project’s aspect ratio. Override with Any / Landscape / Portrait / Square.
• Pins — Pin a clip to keep it at hand. Pinned clips are the Pexels videos saved in your Stock Library, so anything you save on the start page shows up here too.
• Collections — Turn on the pin toggle in the search field to see your pinned clips grouped by Stock Library collection, with an Uncategorized section for clips that aren’t in one. Click a section header to collapse it. The search field filters pinned clips by title, creator, note and keyword. Right-click any clip → Add to Collection to file it into an existing collection or a new one.
• Results paginate; scroll to the bottom to load more.
• Selecting a clip adds it to the active track’s video playlist (or creates a new Video Player track if nothing is selected).

Giphy (GIFs)

Giphy provides animated GIFs. Open the Giphy tab in the browser to search or browse trending GIFs.

• Without a search query, trending GIFs are shown.
• Scroll to the bottom to load more results.
• GIFs are added to the active track’s GIF playlist, or create a new GIF Player track.

Unsplash (images)

Unsplash provides high-resolution royalty-free photography. Open the Unsplash tab in the browser.

• Without a search query, popular/editorial photos are shown.
• Search returns landscape-oriented results by default.
• Results paginate; scroll to load more.
• Pins — Pinned photos are shared with your Stock Library and are grouped by collection, the same way as in Pexels.
• Adding a photo triggers the Unsplash download endpoint as required by their API guidelines.

Stock Library (start page)

The Stock tab on the start page is a full-size browser for Pexels and Unsplash, plus a personal library of clips and photos you’ve saved.

Browsing

• Switch between Videos (Pexels), Pexels Photos, and Unsplash at the top. Search, or leave the field empty to see each provider’s featured feed. Recent searches and suggested VJ terms are shown as chips under the search field.
• Filters: orientation for all sources, plus duration and minimum quality (HD+, Full HD+, 4K) for Pexels videos, color for photos, and Relevant/Latest order for Unsplash.
• Hover a video tile to play a muted preview. Click a tile to open it in a lightbox with a large looping preview and the details panel beside it. Use the arrows or the ← / → keys to step through the grid, and press Esc, click the ✕, or click outside to close it.
• Find Related shows similar items. Unsplash has a native related-photos feed. For Pexels, Arkestra searches on keywords from the clip’s title, and the header shows which keywords it used.
• More from creator lists everything an Unsplash photographer has posted. Pexels doesn’t let apps list a creator’s uploads, so for Pexels creators you get the items you’ve saved from them and an Open Profile button.
• Use Back to return to where you were after following related or creator links.

Saving and organising

• Click the heart on a tile, or Save in the details panel, to add an item to your library. A toast at the bottom confirms the save and shows chips for your three most recently used collections, plus New, so you can file the item without leaving the grid. Undo reverses the save. Once a tile is saved, its heart stays filled. Click it to file the item into collections, create a new one, or Remove from Library. If the tile is part of a selection, the heart acts on the whole selection. Removing an item shows the same toast, and Undo brings it back with its collections and note.
• Collections: create them with + in the left sidebar, from the right-click menu (Add to Collection → New Collection…), or by dragging tiles onto a collection. An item can be in any number of collections. Saved tiles show a badge with the collections they’re in, and the details panel says where an item is filed.
• Keywords are added automatically. They come from Unsplash’s own photo tags or from the words in a Pexels clip’s title. The sidebar lists keywords that two or more saved items share, and clicking one shows those items. The Filter saved… field also matches keywords.
• Each saved item also has a Note field.
• The sidebar has filters for All Saved, Videos, Photos, Uncategorized (saved items not in any collection), each collection and keyword, and your Top Creators. The library header lets you filter by text and sort by date saved, title, creator, or duration.

Multi-select

⌘-click to toggle tiles and ⇧-click to select a range. With more than one tile selected, a bar appears at the bottom with Save, Collection, Download, and New Project. Press Esc to clear the selection.

Using items

• New Project (in the details panel, the right-click menu, the selection bar, or a collection’s header) opens a new project. All the videos go into one Video Player track as a playlist, and all the photos go into one Image track.
• Download… saves the highest-quality file to disk. When several items are selected, you choose a folder.
• Copy Link and Open on Pexels/Unsplash link to the original page.

Your library is stored locally in Arkestra’s Favorites folder (stock-library.json). Clips you starred in older versions are imported automatically the first time the library loads.

---

Local file handling

The Local Media browser (blue folder icon in the sidebar) manages your local video, image, and GIF library.

Adding media

Action	How
Add Folder	Click Add Folder below the list. Arkestra watches the folder and lists all compatible media files inside it.
Add Files	Click Add Files below the list to pick one or more individual files. They appear in the Single Files section.

The Local tab of Add Content is for picking media only. Its folder icon in the search field (or Open Local Media when the library is empty) opens this panel to add or remove folders and files.

Folders are listed alphabetically, with favorited folders pinned to the top. Single files appear in their own collapsible section.

Browsing and searching

Use the search bar to filter files across all folders and single files by name.

Adding to a track

• Single click a file to select it.
• Double-click (or use the play button on hover) to add it to the selected track — it creates a new Video Player, Image Player, or GIF Player layer depending on the file type.
• When the selected track’s effect has a video, image, or GIF playlist, the browser switches to playlist mode: you can ⇧-click or ⌘-click to multi-select files, then tap Add N to Playlist in the footer to batch-add them all at once.

File access

For local files, Arkestra stores a security-scoped bookmark so the file can be accessed across app restarts without re-prompting. If the file is moved or deleted, the item in the playlist will show a broken-file state until you replace it.

Project files

The Project tab of the Media panel lists every local video, image, GIF and point cloud file the project uses, grouped by track. Each file is tagged with a status:

Status	Meaning
In Project	Copied into the .vfx package. It travels with the project.
External	On disk, outside the project package.
Temporary	In a macOS temp folder that the system cleans up. Collect it into the project.
Missing	Can’t be found. It was moved, renamed or deleted, or its drive isn’t connected.

The status chips at the top show how many files are in each state. Click a chip to show only those files, or All to show everything.

• Scan Folder for Missing Files… — pick a folder. Arkestra searches it and its subfolders, and relinks every missing file whose filename matches.
• Find Missing in Photos Library — looks for missing images, GIFs and videos in your Photos library by filename. The extension is ignored, so a HEIC original still matches a .jpeg reference. Each match is copied into the project and relinked, and originals stored only in iCloud are downloaded. The first time you use it, macOS asks for Photos access.
• Collect N into Project — copies all External and Temporary files into the .vfx package and saves the project. An unsaved project asks for a name first.
• Auto-collect new files — once the project is saved, files you add are copied into the package automatically.

Click the magnifying glass on a missing file to locate it yourself. Right-click any file for Locate…/Replace…, Collect into Project, Reveal in Finder, Show in Inspector (or double-click the row), Copy Full Path and Copy Filename. For a missing file, Reveal Enclosing Folder in Finder opens the deepest folder on its path that still exists, which helps you work out where a drive or folder went.

Missing files

When a project references local files that can’t be found on disk, a yellow missing files banner appears at the bottom of the project window with the number of missing files. Click it to open the Media panel’s Project tab, showing only the missing files. You can dismiss the banner. It comes back if more files go missing.

Media from Photos

When you pick a file from the Photos section of a file dialog, macOS hands Arkestra a temporary copy that it deletes later. Arkestra copies these files straight away: into the project package if the project is saved, otherwise into ~/Documents/Arkestra/Imported Media. It does this again before every save, and when a project opens it rescues any temporary files that are still there. To recover files from older projects that have already gone missing, use Find Missing in Photos Library in the Media panel’s Project tab.