# com.nianticspatial.nsdk.playback

Source: https://www.nianticspatial.com/docs/api/kotlin/com.nianticspatial.nsdk.playback/

playback

---

## Classes

| Name | Type | Summary |
| --- | --- | --- |
| AssetPlaybackDatasetLoader | AssetPlaybackDatasetLoader | 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")`. |
| PlaybackBackgroundView | PlaybackBackgroundView | 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. |
| PlaybackCamera | PlaybackCamera | 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. |
| PlaybackDataset | PlaybackDataset | 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).Create via [PlaybackDataset.loadFrom] with a [PlaybackDatasetSource] (e.g. [AssetPlaybackDatasetLoader]).Use [loadFrom][PlaybackDataset.loadFrom] with a custom [imageDecoder] in unit tests to avoid [BitmapFactory] (not mocked on JVM).**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 funneling all frame loads through a single coroutine dispatcher.If you introduce additional callers, ensure they are serialized.Cache fields are marked [@Volatile][Volatile] so that a value written on a background thread isimmediately 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 doesnot make compound check-then-act sequences atomic. |
| PlaybackDatasetError | PlaybackDatasetError | Errors that can occur when loading or accessing playback dataset data. |
| abstract PlaybackDatasetLoader | PlaybackDatasetLoader | 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. |
| PlaybackSession | PlaybackSession | 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.Call [setOnFrameListener] before [play] to receive each [PlaybackFrame]; the listener may beinvoked from a background thread (post to main in the sample if needed). |

---

## Interfaces

| Name | Type | Summary |
| --- | --- | --- |
| PlaybackDatasetSource | PlaybackDatasetSource | 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

| Name | Type | Summary |
| --- | --- | --- |
| CaptureMetadata | CaptureMetadata | Optional capture-level metadata. |
| CaptureRoot | CaptureRoot | Root structure for the capture JSON file. Required fields per spec; optional may be null. |
| FrameMetadata | FrameMetadata | Per-frame metadata from the capture JSON. Required fields per spec; optional may be null. |
| LocationMetadata | LocationMetadata | Location metadata for a frame. All fields optional for varying capture formats. |
| PlaybackFrame | PlaybackFrame | One frame of playback: metadata, camera representation, optional image and depth.Created when a frame is loaded (e.g. by [PlaybackSession]). Use [camera] for pose/intrinsicsand [metadata] for building [FrameData]. |
| PlaybackGpsLocation | PlaybackGpsLocation | GPS location from playback metadata (no Android dependency). Use [toLocation] to obtain[android.location.Location] for [FrameData.location]. Testable without mocking Android. |

---