Paid Assets + Accessories Frame Angel Player Pro

Frame Angel Player Pro is a new type of media player for VaM, a built-from-scratch alternative to ImagePanel.

Player Pro exposes everything you need with buttons and sliders, and keeps you from hunting through a plugin ui.

• Plays supported image and video media on an in-scene CustomUnityAsset screen.
• Loads user media through the player UI/plugin path.
• Supports image and video playlists, including directory-based playback.
• Provides play, pause, next, previous, seek/scrub, volume, mute, loop, shuffle, and favorites behavior.
• Restores player-owned scene state from saved scenes.
• Uses packaged player assets and scripts with short package paths.
• Includes a ready-to-load theater scene.
• Adds on-screen controls that can operate without opening the plugin UI.
• Adds playlist overlay/cards, saved playlist management, and default playlist controls.
• Adds gaze focus, screen focus rim, pointer hiding, and VaM navigation capture while the player owns focus.
• Adds gaze-targeted joystick control for scrub, navigation, and volume.
• Adds configurable skip, slideshow interval, aspect mode, and display size controls.
• Includes Custom/Atom/CustomUnityAsset/Preset_fapp.vap for adding a Pro player instance.

You look, you control.

Your controller joystick skips images at variable speed, navigates movies, scrubs through movies, toggle play for movies and image slide shows, adjusts volume, adjusts screensize, and activates playlists, channels and favorites.

You don't have to click on buttons. You look at a screen, and your controller becomes a media remote.

Current features:

• Includes the Player playback foundation.
• Adds on-screen controls that can operate without opening the plugin UI.
• Adds playlist overlay/cards, saved playlist management, and default playlist controls.
• Adds gaze focus, screen focus rim, pointer hiding, and VaM navigation capture while the player owns focus.
• Adds gaze-targeted joystick control for scrub, navigation, and volume.
• Adds configurable skip, slideshow interval, aspect mode, and display size controls.
• Includes Custom/Atom/CustomUnityAsset/Preset_fapp.vap for adding a Pro player instance.

Frame Angel Player Pro Demo​

Frame Angel Player Pro Demo is the showcase/demo package.

Current features:

• Includes the Pro Demo player surface and bundled curated demo media.
• Includes packaged demo channel presets and demo_channel_manifest.json.
• Shows packaged demo channels without requiring local media setup.
• Includes a ready-to-load theater demo scene.

Future features​

Packages​

All three current package scenes have a dependency on FrameAngel.Theater.1 for their demo scenes.

Frame Angel Player API Reference V1​

The product authority is the player: its broker actions, attached-host selectors, storables, state payloads, product gates, and control-surface trigger contract.cepted screen-body runtime behavior.

Product Boundary​

The player API is exposed in two layers:

1. Broker actions: call Player.* action ids through the plugin broker storable surface.
2. Attached/control-surface actions: authored controls and deterministic controls trigger player behavior through bound control-surface elements.

JSON Argument Rules​

The runtime parser is intentionally small and flat. It reads string, bool, float, object, and array fields by key.

Important conventions:

• String args must be JSON strings.
• Numeric args must be JSON numbers.
• Bool args may be JSON booleans or strings accepted by bool.TryParse; string "1" and "0" are also accepted.
• List args are JSON string arrays.
• Unknown args are ignored unless an action explicitly reads them.
• correlationId and messageId are optional pass-through event identifiers.

Player Selection​

Most standalone player actions require a selected runtime record.

Selectors:

Hosted CUA players use this canonical shape:

{
"instanceId": "hosted_player_host:<hostAtomUid>",
"slotId": "screen_surface",
"displayId": "main",
"playbackKey": "hosted_player_host:<hostAtomUid>::main"
}

Attached plugin UI actions build that selector automatically for the current host. External broker clients should pass the selector explicitly unless they are calling one of the bridge actions that resolves a host atom.

Actions that can create or bind a record:

• Player.LoadPath can create a record for a valid instanceId plus slot or display target.
• Player.SetPlaylist can create a record for a valid writable target.
• Player.BindScreen creates or refreshes the screen-bound record.
• Player.BindControlSurface can resolve or create a target record for a control surface.

Actions that require an existing record:

• Playback, seek, skip, volume, mute, loop, random, slideshow interval, favorites-current actions, gated A-B loop actions, VR video actions, and resize.

Shared Values​

Aspect Modes​

Accepted arg keys: aspectMode, displayMode, screenMode.

Runtime values:

Unrecognized values fall back through the same media-parity normalization used by the runtime. Direct Player.SetAspectMode requires an explicit aspect arg.

Loop Modes​

Accepted arg keys: loopMode, mode, value; bool aliases loop and isLooping are accepted where a loop flag is expected.

Playlist Sources​

Accepted arg keys: playlistSource, source.

auto_channel also reads autoChannelId or channelId.

Skip Seconds​

Accepted arg keys: seconds, deltaSeconds, skipSeconds, amountSeconds.

Configured choices: 15, 30, 60, 120, 300, 600 seconds.

Requested values are normalized to the nearest configured choice. Invalid, non-positive, NaN, or infinite values normalize to the default 15.

Slideshow Interval Seconds​

Accepted arg keys: seconds, intervalSeconds, slideshowIntervalSeconds, value.

Configured choices: 0.25, 0.50, 0.75, 1, 2, 5, 10 seconds.

Requested values are clamped to 0.25..10 and normalized to the nearest configured choice. Invalid values normalize to the default 1.

Seek Values​

Seek seconds arg keys: seconds, timeSeconds, positionSeconds, seekSeconds, value.

Seek normalized arg keys: normalized, normalizedTime, seekNormalized, progress, value.

Normalized seek values are clamped to 0..1.

Direct Broker Action Index​

State API​

Player.GetState returns the standalone state shape when a selector is passed or when the runtime has standalone player records. The payload schema is standalone_player_state_v1.

Payload:

{
"schemaVersion": "standalone_player_state_v1",
"recordCount": 1,
"records": []
}

Record fields:

Media And Playlist Actions​

Player.LoadPath​

Purpose: load one media path into a player record. If a playlist array is provided, the player uses that list and selects the matching/current item.

Args:

Behavior:

• Images default to desiredPlaying=false; videos default to playing unless autoPlay/play says otherwise.
• If no playlist is provided, the media path becomes a one-item playlist.
• Playlist changes clear random history.
• If random=true, the random order is initialized around the selected item.
• Unsupported media paths fail.
• Pro demo packaged media bypasses loose filesystem probing when the requested packaged playlist is admitted by the curated demo content policy.

Success payload: selected standalone state.

Example:

{
"playbackKey": "hosted_player_host:fapp::main",
"mediaPath": "Custom/Images/demo/movie.mp4",
"playlist": [
"Custom/Images/demo/movie.mp4",
"Custom/Images/demo/still.jpg"
],
"currentIndex": 0,
"play": true,
"loopMode": "playlist",
"random": false
}

Player.SetPlaylist​

Purpose: replace the playlist for a player record without requiring a new primary media path.

Availability: FRAMEANGEL_FEATURE_ADVANCED_CONTROLS.

Required: writable target and a non-empty playlist array.

Additional args:

Default loadCurrent: true if the record has no media path yet, otherwise false.

Success summary: player_playlist ok.

Player.LoadNone​

Purpose: clear the media from the selected player while keeping the record.

Required: selector.

Success payload: selected standalone state with no media loaded.

Player.Clear​

Purpose: clear standalone player records. With a selector it clears that record; without a selector it can clear the broader standalone registry.

Use this as a runtime reset action, not as playlist navigation.

Transport Actions​

Player.Play​

Required: selector.

Behavior:

• For still images, starts slideshow mode and resets the slideshow timer.
• For videos, sets desiredPlaying=true and starts/resumes the VideoPlayer when prepared.
• Only in a build where A-B runtime is explicitly available: if A-B loop is enabled and current time is outside the loop range, play seeks to the A point first. Current launch builds keep A-B unavailable.

Success summary: player_play ok.

Player.Pause​

Required: selector.

Behavior:

• Sets desiredPlaying=false.
• For images, stops slideshow mode.
• Clears seek resume state.
• Pauses VideoPlayer when present.

Success summary: player_pause ok.

Player.Next And Player.Previous​

Required: selector.

Behavior:

• Fails if the playlist is empty.
• Uses random order when randomEnabled=true.
• Respects playlist loop mode at the ends.
• Stops image slideshow when manually changing images.
• Navigating to video sets desiredPlaying=true.
• Navigating to an image does not force play unless slideshow is active.

Success summaries: player_next ok, player_next no_change, player_previous ok, player_previous no_change.

Player.SeekToSeconds​

Required: selector plus seek seconds.

Behavior:

• Target is clamped to >=0.
• If duration is known, target is clamped to duration.
• If the player desired state is playing, seek tries to resume.

Success summary: player_seek_seconds ok.

Player.SeekNormalized​

Required: selector plus normalized value.

Behavior:

• Normalized value is clamped 0..1.
• For images, normalized seek maps to a playlist index. With one image, it selects index 0; with multiple entries, it rounds normalized * maxIndex.
• For videos, normalized seek maps to current duration.
• If duration is unknown, only normalized values the media parity seam can seek without known duration are accepted.
• Success summary: player_seek_normalized ok.

Player.SkipBySeconds​

Required: selector plus explicit skip seconds.

Behavior:

• Applies signed seconds directly.
• Fails when timeline is unavailable.
• Resulting seek target follows normal seek clamping.

Success summary: player_skip ok.

Player.SkipForward And Player.SkipBackward​

Required: selector.

Args:

• Optional skip seconds aliases override the configured skip quantum.
• Without explicit seconds, the record's normalized configured skipSeconds is used.

Success summary: player_skip ok.

Player.SetSkipSeconds​

Availability: FRAMEANGEL_FEATURE_ADVANCED_CONTROLS.

Required: selector plus skip seconds aliases.

Behavior:

• Normalizes to nearest configured choice.
• Writes record.skipSeconds.

Success summary: player_skip_seconds ok.

Playback Setting Actions​

Player.SetVolume​

Required: selector plus volume number.

Behavior:

• Clamps volume to 0..1.
• Writes storedVolume.
• Effective volume becomes 0 when muted, otherwise storedVolume.
• Applies the audio state to the runtime player.

Success summary: player_volume ok.

Player.SetMute​

Required: selector plus muted or mute bool.

Behavior:

• Writes record.muted.
• Effective volume becomes 0 when muted, otherwise storedVolume.
• Applies the audio state to the runtime player.

Success summary: player_mute ok.

Player.SetLoopMode​

Required: selector plus loop mode aliases or bool loop aliases.

Behavior:

• Normalizes mode to none, single, or playlist.
• Applies the loop mode to the runtime player.

Success summary: player_loop_mode ok.

Player.SetRandom​

Purpose: turn playlist random/shuffle mode on or off for a specific player record.

Required: selector plus one bool arg:

Behavior:

• Writes record.randomEnabled.
• When enabled, calls the random-order builder with the current playlist index as the anchor and forces a rebuild.
• When disabled, clears random history and random order.
• The current item remains the anchor when random is enabled. The next random step starts from that current item instead of jumping immediately.
• Playlist replacement clears random history; if random is still enabled, a fresh random order is built for the new playlist.
• Player.Next and Player.Previous use the random order and history while randomEnabled=true.
• The generated random order is internal. It is not serialized in the public state payload; public state reports only randomEnabled.

Errors:

Success summary: player_random ok.

Example request:

{
"playbackKey": "hosted_player_host:fapp::main",
"random": true
}

Example result shape:

{
"ok": true,
"summary": "player_random ok",
"message": "player_random ok",
"payload": {
"schemaVersion": "standalone_player_state_v1",
"recordCount": 1,
"records": [
{
"playbackKey": "hosted_player_host:fapp::main",
"randomEnabled": true
}
]
}
}

The actual result record includes all state fields listed in the State API section; the example is shortened to the fields relevant to random mode.

Player.SetSlideshowInterval​

Availability: FRAMEANGEL_FEATURE_ADVANCED_CONTROLS.

Required: selector plus slideshow interval aliases.

Behavior:

• Normalizes to nearest configured interval.
• Writes record.slideshowIntervalSeconds.
• Resets the slideshow timer.

Success summary: player_slideshow_interval ok.

Player.SetAspectMode​

Availability: FRAMEANGEL_FEATURE_ADVANCED_CONTROLS.

Required: selector plus aspect aliases.

Behavior:

• Resolves the requested aspect mode.
• Writes record.aspectMode.
• Marks the screen for refresh.

Success summary: player_aspect_mode ok.

Player.SetDisplaySize​

Availability: FRAMEANGEL_FEATURE_ADVANCED_CONTROLS.

Required: selector plus at least one size target:

Behavior:

• Actual mutation is the VaM host atom Scale parameter.
• Host scale is clamped to 0.10..100.
• Width/height targets derive a scale multiplier from the current screen plane.
• If both width and height are provided, the request fails if it would require non-uniform scaling by more than 0.05.
• Smooth resize emits player_display_size ok immediately, then emits player_resize_finished when complete.

Success summary: player_display_size ok.

Example:

{
"playbackKey": "hosted_player_host:fapp::main",
"targetHostScale": 1.6,
"resizeBehavior": "smooth",
"resizeSeconds": 0.25,
"resizeAnchor": "bottom_anchor"
}

Favorites API​

Favorites are player-owned state stored at:

Custom\PluginData\FrameAngel\Player\favorites\player_favorites_v1.json

Collection schema:

{
"schema": "frameangel_player_favorites_v1",
"collectionId": "favorites",
"displayName": "Favorites",
"entries": [],
"selectedMediaPath": "",
"updatedAtUtc": ""
}

Entry schema:

{
"mediaPath": "",
"displayName": "",
"addedAtUtc": ""
}

Favorites state payload:

Player.AddFavoriteCurrent​

Required: selector resolving a record with supported current media.

Behavior:

• Adds the current media if missing.
• Selects the current media in the favorites collection.
• Writes the collection file.
• Refreshes the favorites UI chooser.

Success summaries: player_favorite_added or player_favorite_selected.

Player.RemoveFavoriteCurrent​

Required: selector resolving a record with supported current media.

Behavior:

• Removes the current media when present.
• Moves selection to a successor entry when needed.
• Marks a favorites-backed playlist for refresh.

Success summaries: player_favorite_removed or player_favorite_missing.

Player.ClearFavorites​

Required: no selector required, but selector can be passed to shape state.

Behavior:

• Clears entries and selected media path.
• Writes the collection file.

Success summary: player_favorites_cleared.

Player.SetFavoritesSelection​

Args:

Passing empty or none clears the selected favorite. Passing a path that is not already in favorites fails with favorite selection not found.

Success summary: player_favorites_selection ok.

Player.LoadFavorites​

Required: selector.

Behavior:

• Builds a valid favorites playlist from supported existing entries.
• Selects the collection selected path.
• Activates that playlist on the selected record.
• Sets playlist source to favorites.
• Clears selected preset id.

Success summary: player_load_favorites ok.

Presets And Playlist Storage​

Preset storage is plugin UI and file-backed product state, not a separate broker action family. Control surfaces can trigger preset slots through their element action ids.

Paths:

Preset schema id: frameangel_player_preset_v1.

Preset record fields:

Preset-related storables:

Plugin Storable Surface​

Version And Summary​

Operator Playback Controls​

Operator Presentation Settings​

These are player-owned per-host settings. They are scene-stored/restorable and hidden by default unless the current profile exposes the presentation toggle UI.

Pointer hiding rule:

VaM controller rays hide only when all of these are true:

• live gaze is actively on a screen,
• Controls Hidden is true.

Scene-State Persistence Contract​

Hosted scene-state is player-owned. It persists media selection, playlist state, current index, presentation settings, and the saved gaze/control visibility state through FrameAngelPlayerSceneState.

pro_demo packaged channel presets are discovered through the packaged demo manifest at:

Custom/PluginData/FrameAngel/Player/presets/demo_channel_manifest.json

Raw dev deploys package demo_curated content into the current discoverable dev package family under AddonPackages so lean roots can exercise the same packaged-demo discovery path as normal package tests.

Hosted Routing Settings​

Default Image API​

Storable:

The default image is a player fallback visual. It is not a scene dependency.

​

Example Calls​

Enable Random/Shuffle​

Broker fields:

{
"playbackKey": "hosted_player_host:fapp::main",
"random": true,
"correlationId": "demo-random-on"
}

Expected result:

• ok=true
• summary=player_random ok
• payload is selected standalone state
• state field records[0].randomEnabled=true

Seek To 75 Percent​

{
"playbackKey": "hosted_player_host:fapp::main",
"normalized": 0.75
}

Action id: Player.SeekNormalized.

Resize To Host Scale 1.6​

{
"playbackKey": "hosted_player_host:fapp::main",
"targetHostScale": 1.6,
"resizeBehavior": "smooth",
"resizeSeconds": 0.25
}

Action id: Player.SetDisplaySize.

Trigger An Authored Random Button​

{
"controlSurfaceInstanceId": "player_controls_left",
"actionId": "random_toggle"
}

Action id: Player.TriggerControlSurfaceElement.

This toggles Player.SetRandom for the bound player target, unless controls are hidden or screen interaction lock blocks the element.

​

​