Skip to main content
←API Reference

playback


Classes​

NameTypeSummary
AssetPlaybackDatasetLoaderAssetPlaybackDatasetLoader
Loads playback dataset data from the app's [Context.getAssets] directory.
Use a subdirectory that contains a capture JSON file and the frame images (and optional depth files).
Example: place a dataset in src/main/assets/playback/my_capture/ with
capture.json, frame_00000000.jpg, etc. Then use
AssetPlaybackDatasetLoader(context, "playback/my_capture").
CachedPlaybackCachedPlayback
A scan in the playback cache.
PlaybackBackgroundViewPlaybackBackgroundView
A view that displays the current playback frame image as the background.
Place this view behind your 3D/GL surface when in playback mode and call [setPlaybackFrame]
whenever a new [PlaybackFrame] is delivered so the recorded camera image is shown.
Orientation is corrected so that the image (which may be stored in sensor/landscape layout)
is rotated to match the current device orientation using [ImageMath.displayTransform].
Use with [PlaybackSession] and a frame listener: when the session delivers a frame,
build [FrameData] for NSDK and call [setPlaybackFrame] to update this view.
PlaybackCacheSessionPlaybackCacheSession
Opens scan recordings from the Niantic Spatial portal through one
[com.nianticspatial.nsdk.NSDKSession], caching them on the device.
The NSDK session creates it on its creating thread and holds one acquisition, so it is ready
at nsdkSession.playbackCache from any thread. Closing the NSDK session ends it: an open in
flight then fails, and every later call fails, with [PlaybackOpenError.SESSION_ENDED].
Thread-safe.
Two locks guard the native calls: this session's own monitor, which [close] and [destroy] take,
ends the cache cleanly; [NativeHandle]'s read lock keeps the NSDK instance alive underneath, so
a call after the NSDK session is closed, even an [acquire], receives a null handle rather than
a freed one.
PlaybackCameraPlaybackCamera
Camera representation for playback, built from frame [metadata]. Exposes transform, intrinsics, resolution,
tracking state, and orientation. Use [toArCorePose] to build a [Pose] for [FrameData.cameraPose].
Use [getViewMatrix] and [getProjectionMatrix] to drive a virtual camera for playback rendering.
PlaybackDatasetPlaybackDataset
A playback dataset loaded from a capture JSON file.
Uses on-demand loading for frame images and depth: only the requested frame is loaded and cached (1-frame cache).
Open with [open], which reads the dataset through native playback. The [loadFrom]
path over a [PlaybackDatasetSource] is deprecated and will be removed in a future release. [close] releases
native resources.
Thread safety: This class is NOT thread-safe. All methods must be called from a single thread.
The 1-frame cache ([cachedFrameIndex], [cachedImageBytes], [cachedDepthData], [cachedConfidenceData])
is not protected by a lock; concurrent reads and writes will produce inconsistent results.
[PlaybackSession] satisfies this constraint by loading frames on one worker thread at a time.
If you introduce additional callers, ensure they are serialized.
Cache fields are marked [@Volatile][Volatile] so that a value written on a background thread is
immediately visible to any thread that subsequently reads it (e.g. the main thread checking
[cachedFrameIndex] before deciding to reload). This is a visibility guarantee only — it does
not make compound check-then-act sequences atomic.
PlaybackDatasetErrorPlaybackDatasetError
Errors that can occur when loading or accessing playback dataset data.
PlaybackDatasetInfoPlaybackDatasetInfo
Capture-level facts about a playback dataset. Mirrors ARDK_PlaybackDataset_Info.
abstract PlaybackDatasetLoaderPlaybackDatasetLoader
Base class for loading playback dataset data from various sources.
Subclasses override [loadCaptureJson], [loadImage], [loadDepthData], [loadDepthConfidence] to provide concrete implementations.
Use [loadDataset] to parse the capture JSON and create a [PlaybackDataset] that uses this loader for on-demand frame loading.
PlaybackFileInfoPlaybackFileInfo
The recording [PlaybackCacheSession.open] plays for a scan, as the portal lists it. For a
chunked scan, every value is the first (playing) chunk's.
PlaybackFrameMetadataPlaybackFrameMetadata
One frame's recorded data, without its image or depth buffers. Mirrors the frame native playback
returns from ARDK_PlaybackDataset_GetFrameMetadata; [transform] is in the recorded (ARCore)
convention.
PlaybackImageUtility.YuvImageHandlerYuvImageHandler
Holds a YUV [Image] and its [ImageReader]/[ImageWriter]; call [close] when done.
PlaybackOpenExceptionPlaybackOpenException
Thrown by [PlaybackDataset.open] with a scan ID when the open fails.
PlaybackSessionPlaybackSession
Runs a timed loop over a [PlaybackDataset], loading one frame per tick and notifying a listener.
Use [play] to begin playback and [pause] to stop; the loop wraps to frame 0 at end, and each
later pass has its timestamps moved one recording's length later so they keep increasing.
Call [setOnFrameListener] before [play] to receive each [PlaybackFrame]; the listener is
invoked on a background thread, one frame at a time (post to the main thread before touching
UI). An exception thrown by the listener is logged and playback continues; an error loading a
frame is logged and stops playback.

Interfaces​

NameTypeSummary
PlaybackDatasetSourcePlaybackDatasetSource
Abstraction for loading playback dataset data from a source (assets, file, etc.).
Used for on-demand frame loading: [PlaybackDataset] calls these methods when frames are requested.

Data Classes​

NameTypeSummary
CaptureMetadataCaptureMetadata
Optional capture-level metadata.
CaptureRootCaptureRoot
Root structure for the capture JSON file. Required fields per spec; optional may be null.
FrameMetadataFrameMetadata
Per-frame metadata from the capture JSON. Required fields per spec; optional may be null.
LocationMetadataLocationMetadata
Location metadata for a frame. All fields optional for varying capture formats.
PlaybackDatasetError.ImageLoadFailedImageLoadFailed
Frame image could not be loaded: missing image filename in metadata or loader could not read the file.
PlaybackDatasetError.IndexOutOfBoundsIndexOutOfBounds
Requested frame index is outside the dataset (e.g. negative or >= frame count).
PlaybackFramePlaybackFrame
One frame of playback: recorded data, camera representation, optional image and depth.
Created when a frame is loaded (e.g. by [PlaybackSession]). Use [camera] for pose/intrinsics
and [frameMetadata] for the frame's recorded data.
PlaybackGpsLocationPlaybackGpsLocation
GPS location from playback metadata (no Android dependency). Use [toLocation] to obtain
[android.location.Location] for [FrameData.location]. Testable without mocking Android.

Enums​

NameTypeSummary
CachedPlaybackStateCachedPlaybackState
How far a cached scan's recording got.
PlaybackOpenErrorPlaybackOpenError
Why [PlaybackDataset.open] with a scan ID failed.

Functions​

NameTypeSummary
cameraImageHeightInt
Image height in pixels (resolution[1]).
cameraImageWidthInt
Image width in pixels (resolution[0]).
cameraIntrinsicsCameraIntrinsics
[CameraIntrinsics] from metadata (fx, fy, cx, cy) and resolution [width, height].
cameraTimestampMsLong
Timestamp in milliseconds (timestamp × 1000).
cameraTransformFloatArrayFloatArray
Column-major 4×4 transform (pose4x4) as FloatArray of 16 elements for use with ARCore and rendering.
compassDataCompass?
[Compass] from location metadata when heading is present; null otherwise.
gpsLocationLocation?
Android [Location] from frame location metadata when lat/long present; null otherwise.
orientationOrientation
Screen orientation from metadata string; UNKNOWN if missing or unrecognized.
playbackGpsLocationPlaybackGpsLocation?
Parsed GPS location from frame metadata when lat/long present; null otherwise. Use this in tests.
trackingStateTrackingState
Tracking: 0 → STOPPED, 1 → PAUSED, 2 (or other) → TRACKING.