# Create playback datasets Source: https://www.nianticspatial.com/docs/nsdk/how-to/playback/create_playback_dataset/?platform=kotlin ## Introduction Use NSDK Recording to capture motion and sensor data from an AR session. You can export the recording as a playback dataset for testing and debugging. Kotlin Capture sample recording and exporting a playback dataset. The sample app is Niantic's working Kotlin reference app. Its Capture screen demonstrates a complete recording and export flow, and its source files provide reference code for your own integration. Start by [getting the sample app](#kotlin-get-the-sample-source), then choose one of these independent workflows: - **[Capture](#kotlin-capture-sample):** Use the existing Capture screen to create a dataset quickly. - **[Recording API](#kotlin-api-record):** Build a tutorial screen when you need control over the UI, capture state, export progress, or sharing behavior. You do not need to complete the Capture workflow before using the Recording API workflow. In the Kotlin instructions: - **Sample app** means Niantic's downloaded `nsdk-samples-kotlin` project. - **Tutorial screen** means the `PlaybackCaptureScreen` you create. - **Your app** means the application where you will integrate the completed screen. ## Get the sample app Both workflows use the public [`nsdk-samples-kotlin`](https://github.com/nianticspatial/nsdk-samples-kotlin) repository. After opening the repository, either run the existing Capture sample UI or use its Capture source files as reference code for your own app. Clone the repository: ```bash git clone https://github.com/nianticspatial/nsdk-samples-kotlin.git ``` Alternatively, select **Code > Download ZIP** on GitHub, then extract the ZIP before opening it in Android Studio. The repository contains a nested Android Studio project: ```text nsdk-samples-kotlin/ └── NsdkSamples/ <- Open this directory in Android Studio ├── settings.gradle.kts ├── gradlew └── NsdkSamples/ <- Application module; do not open this directory by itself ``` Open the sample source as follows: 1. Launch Android Studio. 2. Select **File > Open**. 3. Select `/nsdk-samples-kotlin/NsdkSamples`, the directory containing `settings.gradle.kts` and `gradlew`, then select **Open**. 4. If Android Studio asks whether to trust the project, select **Trust Project**. 5. Wait for Gradle sync and indexing to finish. If sync does not start automatically, select **File > Sync Project with Gradle Files**. ## Record with Capture The Kotlin capture sample is the fastest way to create a playback dataset on Android without first building your own recording interface. Use it when you want to validate the workflow quickly, generate a dataset for testing, or compare your own implementation against a working sample. To record a playback dataset using the existing sample UI: 1. [Run Capture](#kotlin-open-the-sample-and-start-recording) 2. [Record the environment](#kotlin-record-the-environment) 3. [Export the dataset](#kotlin-stop-and-export-the-dataset) ### Run Capture 1. Connect an ARCore-compatible Android device with USB debugging enabled, then select it in Android Studio's target-device menu. 2. Select the `NsdkSamples` run configuration and select **Run**. 3. On the device, grant the requested camera and location permissions and complete the sample app's sign-in flow. 4. From the sample list, open **Capture**. 5. Tap **Start Capture** and confirm the camera view opens and the recording controls respond. For more information about the other sample screens, see [Kotlin Sample Projects](https://www.nianticspatial.com/docs/nsdk/sample_projects/#kotlin-sample-projects). ### Record the environment Record the environment using your device's camera. Keep in mind the following: - Keep your device in **Portrait Mode**. - Hold your device as steadily as possible to reduce errors in the dataset. ### Export the dataset Tap **Stop Capture** to finish recording. When you are ready, tap **Export Capture** to process your most recent recording into a Playback format dataset. With `ScannerConfig.basePath` unset, the sample stores scans under: `/sdcard/Android/data/{app.package.name}/files/scankit/` After the export is complete, the sample app opens Android's share sheet for the resulting `.tgz` archive. The available destinations depend on the apps installed on your device and can include services such as Google Drive, Gmail, Quick Share, or Bluetooth. The sample uses Android's `ACTION_SEND` intent, so it does not guarantee that the share sheet includes a **Save to device** option. To display the completed export path, connect the device and run: ```bash adb logcat -d -s CaptureManager:I ``` Find the line containing `Export completed`, for example: ```text I CaptureManager: Export completed: /storage/emulated/0/Android/data/com.example.app/files/scankit/SCAN_ID/chunk_0.tgz ``` Copy the full `.tgz` path from that line, then pass it to `adb pull`: ```bash adb pull /storage/emulated/0/Android/data/com.example.app/files/scankit/SCAN_ID/chunk_0.tgz . ``` The final `.` copies the archive into the terminal's current directory. ## Record with the API If the Recording sample is too limited for your project, you can create your own recording app instead. The Kotlin API gives you full control over the recording experience, including the UI, capture state, export progress, and sharing behavior. Use this approach when you want dataset creation to fit naturally into your app instead of relying on the sample screen. This workflow uses the sample app as a runnable development environment. The sample app shows how capture responsibilities are divided, and the tutorial builds a separate recording screen in the sample app before moving the finished integration into an app. The new screen gives you control over the Compose UI, recording and save state, the frame-count gate, export progress, and Android sharing. The sample app supplies the authenticated `NSDKSession`, ARCore frame delivery, and AR screen needed to run each stage. The API walkthrough contains these sections: 1. [Capture implementation overview](#kotlin-capture-implementation-overview) 2. [Prepare the sample app](#kotlin-grant-permissions-and-sign-in) 3. [Create the tutorial screen](#kotlin-create-the-screen-and-its-state) 4. [Add capture controls](#kotlin-connect-state-to-the-compose-controls) 5. [Start capture](#kotlin-start-capture) 6. [Stop and save](#kotlin-stop-and-save-safely) 7. [Export the archive](#kotlin-export-the-archive-and-report-progress) 8. [Share the archive](#kotlin-share-the-exported-archive) 9. [Retrieve and verify the recording](#kotlin-retrieve-and-verify-the-recording) 10. [View the complete PlaybackCaptureScreen](#kotlin-complete-api-example) 11. [Add to your app](#kotlin-add-the-screen-to-your-app) --- ### Capture implementation overview The API walkthrough starts from Niantic's Capture implementation in the sample app. These sample files provide the runtime environment and reference implementation for the tutorial screen: | File | Responsibility | | --- | --- | | `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/CaptureManager.kt` | Owns the scanning session, saved scan information, frame count, and recording exporter. | | `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/CaptureView.kt` | Creates `CaptureManager` from the active NSDK session and renders the Compose capture, save, export, and progress controls. | The tutorial creates a separate `PlaybackCaptureScreen.kt` so Niantic's Capture reference implementation remains unchanged. When the finished screen moves into an app, that app must provide an authenticated `NSDKSession` that is already receiving live ARCore frames, camera and location permissions, and product-specific archive sharing or upload behavior. Apps without that runtime setup need the configuration described in [Setting Up the Niantic SDK in Kotlin](https://www.nianticspatial.com/docs/nsdk/setup/). Standalone development or internal-test builds can use a developer token from **Credentials > Developer Tokens** in [Scaniverse web](https://scaniverse.nianticspatial.com/signin): `NSDKSession(accessToken = "YOUR_DEVELOPER_TOKEN")`. Developer tokens should stay out of source control and public builds; see [Authorization](https://www.nianticspatial.com/docs/nsdk/auth_getting_started/) for the production flow. ### Prepare the sample app The sample app needs camera permission to supply AR frames and location permission to include device location data in the recording. It also needs an authenticated NSDK session before it can initialize the Recording APIs used by the tutorial. Prepare the sample app on the Android device before adding the new recording screen: 1. Connect an ARCore-compatible Android device and select it in Android Studio's target-device menu. 2. Select the `NsdkSamples` run configuration and select **Run**. 3. On the device, grant camera and location access when prompted. 4. Complete the sample app's sign-in flow. 5. Return to the sample list after sign-in completes. **Validate this step:** 1. Open **Capture** from the sample list. 2. Confirm the camera view opens without another camera, location, or sign-in prompt. 3. Return to the sample list without starting a capture. The sample app retains these permissions and authentication for the implementation steps that follow. When you move the completed screen into your own app, that app must provide the same permissions and an authenticated, frame-fed `NSDKSession`. See [Authorization](https://www.nianticspatial.com/docs/nsdk/auth_getting_started/) for more information about adding authentication to a new app. ### Create the tutorial screen Build the recording integration in a new `PlaybackCaptureScreen.kt` file in the sample app. Use the sample app's existing `CaptureManager.kt` and `CaptureView.kt` files as references for the recording lifecycle and UI behavior; do not modify those two files. The new screen acquires its own scanning session and recording exporter from the sample app's `NSDKSession`. In the Android Studio project pane, create a new `PlaybackCaptureScreen.kt` file at the following path in the sample app module: ```text NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt ``` #### Expand to create PlaybackCaptureScreen.kt with its initial state and placeholders Add the following compiling skeleton to `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`. It acquires the Recording API resources, creates the Compose state, registers lifecycle cleanup, and provides placeholders for the implementation added by each later section: ```kotlin package com.nianticspatial.nsdk.externalsamples.capture import android.content.Context import android.content.Intent import android.util.Log import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.padding import androidx.compose.material3.Button import androidx.compose.material3.LinearProgressIndicator import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.DisposableEffect import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.runtime.setValue import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.platform.LocalContext import androidx.compose.ui.unit.dp import androidx.core.content.FileProvider import com.nianticspatial.nsdk.AsyncResult import com.nianticspatial.nsdk.NSDKSession import com.nianticspatial.nsdk.ScanSaveInfo import com.nianticspatial.nsdk.ScannerConfig import java.io.File import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.Job import kotlinx.coroutines.cancelAndJoin import kotlinx.coroutines.delay import kotlinx.coroutines.launch @Composable fun PlaybackCaptureScreen(nsdkSession: NSDKSession) { // Keep Android context, coroutine work, and acquired NSDK resources scoped to // this screen. In your app, these resources can instead be owned by a ViewModel // or another lifecycle-aware component. val context = LocalContext.current val coroutineScope = rememberCoroutineScope() val scanningSession = remember { nsdkSession.scanning.acquire() } val recordingExporter = remember { nsdkSession.recordingExporter.acquire() } // These Compose values drive the button labels, enabled states, progress bar, // saved-scan availability, and user-visible errors added in later steps. var isRecording by remember { mutableStateOf(false) } var canStopCapture by remember { mutableStateOf(false) } var isSaving by remember { mutableStateOf(false) } var isExporting by remember { mutableStateOf(false) } var exportProgress by remember { mutableStateOf(0f) } var saveInfo by remember { mutableStateOf(null) } var errorMessage by remember { mutableStateOf(null) } // Cancel and join this screen's capture, save, and export work before closing // native resources. If your app owns these resources elsewhere, perform the // equivalent ordered cleanup in that lifecycle owner. DisposableEffect(Unit) { val screenJob = coroutineScope.coroutineContext[Job] onDispose { CoroutineScope(Dispatchers.IO).launch { screenJob?.cancelAndJoin() scanningSession.stop() scanningSession.close() recordingExporter.close() } } } fun startCapture() { // Placeholder: replaced in "Start capture." } suspend fun stopAndSaveCapture() { // Placeholder: replaced in "Stop and save." } suspend fun exportCapture() { // Placeholder: replaced in "Export the archive." } // Placeholder: replaced in "Add capture controls." Text("Playback capture controls") } private fun shareArchive(context: Context, archivePath: String): Boolean { // Placeholder: replaced in "Share the archive." return false } ``` Verify the skeleton before continuing: 1. In Android Studio, select **Build > Assemble Project**. 2. Open the **Build** tool window and confirm the build finishes without errors. `PlaybackCaptureScreen.kt` is a composable source file, not an Android application entry point, activity, or test. Android Studio therefore does not display a file-level Run icon for it. Do not try to run this file directly. After verifying the build, connect the screen to the sample app's Capture route by following the next instructions, then run the `NsdkSamples` application. Each following section replaces one identified placeholder with the next part of the working flow. The screen accepts the sample app's existing `NSDKSession`, acquires the two Recording API objects it needs, and keeps the state that drives its UI: | State | UI behavior | | --- | --- | | `isRecording` | Changes **Start Capture** to the recording state. | | `canStopCapture` | Keeps the stop action disabled until a frame has been recorded. | | `isSaving` | Disables the controls and displays **Saving...**. | | `isExporting` and `exportProgress` | Displays and updates the export progress bar. | | `saveInfo` | Makes **Export Capture** available after a successful save. | | `errorMessage` | Displays save, export, or sharing failures. | These values are Compose state, so changes made by the Recording API immediately update the controls. The skeleton also uses `DisposableEffect` to cancel its running work before stopping capture and closing the acquired native SDK resources when the screen leaves composition. Connect the new screen to the sample app now so you can validate every remaining step on a device: 1. Open: ```text NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/NSDKDemoView.kt ``` 2. Add the following import so `NSDKDemoView.kt` can render the tutorial screen: ```kotlin // Import the tutorial-owned screen so the Capture route can render it. import com.nianticspatial.nsdk.externalsamples.capture.PlaybackCaptureScreen ``` 3. Find the `composable { ... }` block. Inside its `BackHelpScaffold`, replace the existing `CaptureView(...)` call with code that enables live AR frame updates and renders the tutorial screen. Replace only: ```kotlin CaptureView(activity, nsdkSessionManager, helpContentState, overlayContentState) ``` with: ```kotlin // In the unmodified sample, CaptureView owns this AR-session lifecycle. // Preserve that behavior while the tutorial screen replaces CaptureView. DisposableEffect(Unit) { nsdkSessionManager.arManager.setEnabled(true) onDispose { nsdkSessionManager.arManager.setEnabled(false) } } // Pass the sample app's authenticated session into the tutorial screen. PlaybackCaptureScreen(nsdkSession = nsdkSession) ``` In the unmodified sample, `CaptureView` enables the sample app's AR session. Because this route now displays `PlaybackCaptureScreen` instead, the `DisposableEffect` enables the AR session while the tutorial screen is open and disables it when the screen closes. This supplies the live frames that the scanning session records. Keep this temporary routing change in place through the remaining API steps. It lets the sample app provide authentication and live AR frames without changing `CaptureManager.kt` or `CaptureView.kt`. **Validate this step:** 1. Select the `NsdkSamples` run configuration and a connected Android device, then select **Run**. 2. Open **Capture** from the sample list. 3. Confirm the screen displays **Playback capture controls**. This placeholder confirms the sample app is rendering the new file; capture controls are added in the next step. ### Add capture controls The main button starts capture on its first tap and saves on its next enabled tap. `canStopCapture` is the frame-count gate: while it is false, the disabled button displays **Starting Capture...**. The export button appears only after `saveInfo` is available. In `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`, locate `Text("Playback capture controls")` and replace it with the following `Column`. This code connects the capture state to the start, stop, save, and export controls: #### Expand to replace the Kotlin capture controls ```kotlin // Arrange the recording controls vertically. Replace this layout and styling with // your app's design system while preserving the following state checks. Column( modifier = Modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(10.dp), horizontalAlignment = Alignment.CenterHorizontally ) { Button( // Disable the main action during save/export and until capture has written // at least one frame. enabled = !isSaving && !isExporting && (!isRecording || canStopCapture), onClick = { // The same control starts a new recording or saves the active one. // Split these into separate controls if that better matches your UI. if (!isRecording) { startCapture() } else { coroutineScope.launch { stopAndSaveCapture() } } } ) { // Derive the label from capture state so the user can see when stopping is safe. Text( when { isSaving -> "Saving..." !isRecording -> "Start Capture" canStopCapture -> "Stop Capture" else -> "Starting Capture..." } ) } // Show progress only while recordingExporter.export() is running. if (isExporting) { LinearProgressIndicator( progress = { exportProgress }, modifier = Modifier.fillMaxWidth().padding(horizontal = 20.dp) ) } // Offer export only after save() returns the path and ID of a saved scan. if (saveInfo != null && !isRecording && !isExporting) { Button( enabled = !isSaving, onClick = { coroutineScope.launch { exportCapture() } } ) { Text("Export Capture") } } // Replace this inline text with your app's snackbar, dialog, or error component. errorMessage?.let { message -> Text(message) } } ``` **Validate this step:** 1. Select **Build > Assemble Project** and confirm the build finishes without errors. 2. Run `NsdkSamples` and open **Capture**. 3. Confirm **Start Capture** appears and **Export Capture** is not displayed. At this stage, `startCapture()` is still a placeholder. The next step implements the button's capture behavior. ### Start capture In `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`, locate the placeholder `startCapture()` function and replace the entire function with the following code. It configures and starts the scanning session, polls the recorded frame count, and enables the stop action after NSDK saves the first frame: #### Expand to replace the Kotlin start-capture function ```kotlin fun startCapture() { // If your app already has a Start Capture handler, replace its existing // configure/start block with this flow instead of starting a second session. // Ignore duplicate taps while this screen is recording, saving, or exporting. // If your app has a ViewModel or another capture-state owner, perform the // equivalent state check there instead. if (isRecording || isSaving || isExporting) return // Clear results and messages from the previous capture before starting again. // Reset any additional app-specific scan state here as well. saveInfo = null canStopCapture = false errorMessage = null // Customize these values for the capture experience in your app. For example, // reuse your existing ScannerConfig or set basePath if scans should use a // non-default location. Configure the session before calling start(). val config = ScannerConfig().apply { useNsdkDepthsIfPlatformUnavailable = true enableRaycastVisualization = true enableVoxelVisualization = false } scanningSession.configure(config) scanningSession.start() Log.i("PlaybackCaptureScreen", "Capture start requested") // Updating Compose state changes the button to the waiting-for-frames state. // If capture state belongs to your ViewModel, update that state instead. isRecording = true // MultiDepth initialization or a GeographicLib download can delay the first // saved frame, so starting the session does not make stopping safe yet. // If your app owns background work in a ViewModel, move this polling coroutine // there, but keep the frame-count check before enabling the stop action. coroutineScope.launch { while (isRecording) { val frameCount = try { scanningSession.getRecordingInfo().frameCount } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Could not read frame count", exception) 0 } if (frameCount > 0) { // At least one frame is stored, so Stop Capture can now call save(). Log.i( "PlaybackCaptureScreen", "Capture ready to stop; frameCount=$frameCount" ) canStopCapture = true break } // Change the polling interval if your app needs a different UI cadence. delay(200) } } } ``` Calling `scanningSession.start()` requests that capture begin, but capture is not ready to stop until NSDK confirms that it is saving frames. Initialization can be delayed while NSDK prepares the recording session. Treat capture as ready only after `getRecordingInfo().frameCount` is greater than zero. Until then, keep the stop action disabled because saving an empty recording can fail with `INVALID_OPERATION`. **Validate this step:** 1. Select **Build > Assemble Project**, then run `NsdkSamples` and open **Capture**. 2. Tap **Start Capture**. 3. Confirm the button changes to **Starting Capture...** and remains disabled while `frameCount` is zero. 4. Move the device until the button changes to **Stop Capture**, confirming that at least one frame was recorded. 5. Open **View > Tool Windows > Logcat** in Android Studio and enter `tag:PlaybackCaptureScreen` in the Logcat query field. 6. Confirm Logcat contains `Capture start requested` and `Capture ready to stop; frameCount=` with a value greater than zero. ### Stop and save In `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`, locate the placeholder `stopAndSaveCapture()` function and replace the entire function with the following code. It rechecks the frame count, saves a valid recording, and restores the controls after every result. The disabled stop control is the primary frame-count gate, but the second check protects calls from somewhere other than the button. An empty capture is stopped and discarded instead of being passed to `save()`, which can fail with `INVALID_OPERATION`: #### Expand to replace the Kotlin stop-and-save function ```kotlin suspend fun stopAndSaveCapture() { // Ignore duplicate stop taps and calls made outside an active recording. if (!isRecording || isSaving) return // Recheck the frame count at the save boundary. This protects callers other // than the button and prevents save() from receiving an empty recording. val frameCount = try { scanningSession.getRecordingInfo().frameCount } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Could not read frame count before save", exception) 0 } if (frameCount == 0) { // Discard the empty recording and restore the idle UI instead of saving it. scanningSession.stop() isRecording = false canStopCapture = false errorMessage = "Capture stopped before any frames were recorded." return } // Enter the saving state before starting native work so the controls cannot // submit another action. Move this state to your ViewModel if it owns capture. isSaving = true isRecording = false canStopCapture = false try { // save() finalizes the dataset on device and returns the information // required by the exporter. when (val result = scanningSession.save()) { is AsyncResult.Success -> saveInfo = result.value is AsyncResult.Error -> errorMessage = "Save failed: ${result.code}" is AsyncResult.Timeout -> errorMessage = "Save timed out." } } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Save failed with an exception", exception) errorMessage = "Save failed: ${exception.message ?: "Unknown error"}" } finally { // Stop the scanning session and restore the UI after every save outcome. scanningSession.stop() isSaving = false } } ``` On success, `saveInfo` contains the scan ID and saved-scan path required by the exporter. **Validate this step:** 1. Select **Build > Assemble Project**, then run `NsdkSamples` and open **Capture**. 2. Tap **Start Capture** and wait for **Stop Capture** to become enabled. 3. Tap **Stop Capture** and confirm the button displays **Saving...** while the scan is being saved. 4. Confirm **Export Capture** appears after the save succeeds. At this stage, `exportCapture()` is still a placeholder. The next step implements the export behavior. ### Export the archive In `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`, locate the placeholder `exportCapture()` function and replace the entire function with the following code. It passes the saved path and scan ID to the exporter, updates the progress state, and sends the returned archive path to the sharing helper: #### Expand to replace the Kotlin export function ```kotlin suspend fun exportCapture() { // Export requires the non-null path and scan ID returned by a successful save(). val scanInfo = saveInfo ?: return val scanDirPath = scanInfo.savePath val scanId = scanInfo.scanId if (scanDirPath == null || scanId == null) { Log.e("PlaybackCaptureScreen", "Saved scan information is incomplete") errorMessage = "The saved scan is missing its path or scan ID." return } // Reset export UI before starting. Replace these Compose assignments with // updates to your app's state owner when appropriate. isExporting = true exportProgress = 0f errorMessage = null Log.i("PlaybackCaptureScreen", "Export started for scanId=$scanId") try { // Create a playback-compatible archive from the saved scan. Keep // exportAsVideo false for playback datasets; adjust the timeout for your UX. val result = recordingExporter.export( scanDirPath = scanDirPath, scanId = scanId, exportAsVideo = false, timeoutMillis = 300_000, // The callback reports values from 0.0 to 1.0 for the progress indicator. onProgress = { progress -> exportProgress = progress } ) // Share the path returned by the exporter rather than constructing a path. // Replace shareArchive() if your app uploads or manages archives itself. when (result) { is AsyncResult.Success -> { Log.i("PlaybackCaptureScreen", "Export completed: ${result.value}") if (!shareArchive(context, result.value)) { errorMessage = "The archive was exported but could not be shared." } } is AsyncResult.Error -> { Log.e("PlaybackCaptureScreen", "Export failed: ${result.code}") errorMessage = "Export failed: ${result.code}" } is AsyncResult.Timeout -> { Log.w("PlaybackCaptureScreen", "Export timed out") errorMessage = "Export timed out." } } } catch (exception: CancellationException) { Log.i("PlaybackCaptureScreen", "Export cancelled") throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Export failed with an exception", exception) errorMessage = "Export failed: ${exception.message ?: "Unknown error"}" } finally { // Restore the export controls after success, failure, timeout, or cancellation. isExporting = false } } ``` The successful result contains the actual `.tgz` archive path. Pass that path to the sharing helper instead of constructing a path from the default storage location. **Validate this step:** 1. Select **Build > Assemble Project**, then run `NsdkSamples` and create and save a capture. 2. Tap **Export Capture** and confirm the progress bar appears while the archive is created. 3. Open **View > Tool Windows > Logcat** in Android Studio. In the Logcat toolbar, select the connected physical device and the `com.nianticspatial.nsdk.externalsamples` app process, then enter `tag:PlaybackCaptureScreen` in the query field. 4. Confirm Logcat contains `Export started for scanId=` followed by `Export completed:` and the full `.tgz` archive path. 5. Confirm the screen displays **The archive was exported but could not be shared.** This is expected because `shareArchive(...)` is still a placeholder. ### Share the archive In `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt`, locate the placeholder `shareArchive(...)` function and replace the entire function with the following code. It verifies the archive, creates a `FileProvider` content URI, grants temporary read access, and opens Android's share sheet: #### Expand to replace the Kotlin share function ```kotlin private fun shareArchive(context: Context, archivePath: String): Boolean { // Do not open the chooser if the exporter did not create the expected file. val file = File(archivePath) if (!file.exists()) { Log.e("PlaybackCaptureScreen", "Archive not found: $archivePath") return false } // Convert the private file path to a content URI that another app may read. // The FileProvider authority must match the declaration in AndroidManifest.xml. return runCatching { val uri = FileProvider.getUriForFile( context, "${context.packageName}.fileprovider", file ) // Grant the selected destination temporary read access to the archive. val shareIntent = Intent(Intent.ACTION_SEND).apply { type = "application/gzip" putExtra(Intent.EXTRA_STREAM, uri) addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION) } // Replace Android's chooser here if your product has a custom upload flow. context.startActivity(Intent.createChooser(shareIntent, "Share Capture")) Log.i("PlaybackCaptureScreen", "Share sheet opened for archive: $archivePath") true }.onFailure { exception -> Log.e("PlaybackCaptureScreen", "Could not open share sheet", exception) }.getOrDefault(false) } ``` The sample app already declares a `FileProvider` with the matching authority, so no sharing configuration is required while you build and validate the screen there. The complete `PlaybackCaptureScreen` section explains what to add when you move the finished screen into your own app. **Validate this step:** 1. Select **Build > Assemble Project**, then run `NsdkSamples` and create and save a capture. 2. Tap **Export Capture** and wait for export to finish. 3. Confirm Android's share sheet opens with the exported `.tgz` archive. 4. Return to Android Studio and open **View > Tool Windows > Logcat**. The share sheet can change the selected process, so select the connected physical device and the `com.nianticspatial.nsdk.externalsamples` app process in the Logcat toolbar, then enter `tag:PlaybackCaptureScreen` in the query field. 5. Confirm Logcat contains `Share sheet opened for archive:` followed by the same `.tgz` path reported by `Export completed:`. 6. Select a sharing destination or dismiss the share sheet, then confirm the app returns to the Capture screen without an error message. ### Retrieve and verify the recording Use Android Studio to copy the exported recording from the device, then use the operating system's built-in archive support to examine it. This workflow does not require `adb` on the terminal path or Unix shell utilities: 1. In the Logcat validation from **Export the archive**, copy the scan ID from the `Export completed:` path. 2. In Android Studio, select **View > Tool Windows > Device Explorer**, then select the connected device. 3. In Device Explorer, navigate to: ```text sdcard/Android/data/com.nianticspatial.nsdk.externalsamples/files/scankit/ ``` 4. Open the directory whose name matches the scan ID from Logcat, then select `chunk_0.tgz`. 5. Select **Save As** in the Device Explorer toolbar and save the file to the development machine. 6. Extract `chunk_0.tgz` with the operating system's built-in archive support: - On macOS, select the file in Finder, then select **File > Open**. - On Windows 11 version 24H2 or later, select the file in File Explorer, then select **Extract All**. - On Linux, select the file in the system file manager, then select its **Extract** action. The action name depends on the desktop environment. 7. In the extracted directory, confirm that `capture.json` and `frame_*.jpg` files are present. 8. Open `capture.json` in a text editor and locate its top-level `frameCount` property. Confirm that the value is greater than zero. Frame numbering starts at zero, so a `frameCount` of `23` corresponds to files from `frame_00000000.jpg` through `frame_00000022.jpg`. 9. Open several `frame_*.jpg` files and confirm that they show the environment you recorded. Depth and confidence files are device- and configuration-dependent, so their absence does not by itself mean the playback dataset is invalid. To validate the dataset by replaying it, continue with [Set up Playback](https://www.nianticspatial.com/docs/nsdk/how-to/playback/setting_up_playback/). ### View the complete PlaybackCaptureScreen The expandable section contains the complete `PlaybackCaptureScreen.kt` assembled in the preceding steps. Use it to check your completed screen, recover a missed change, or copy the full implementation without repeating the walkthrough. Refer to this code for the tutorial's finished result; Niantic's existing `CaptureView.kt` and `CaptureManager.kt` belong to a separate sample-app implementation and do not correspond line-for-line with these steps. #### Expand to reveal PlaybackCaptureScreen.kt Compare the completed `NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt` with the following code: ```kotlin package com.nianticspatial.nsdk.externalsamples.capture import android.content.Context import android.content.Intent import android.util.Log import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.padding import androidx.compose.material3.Button import androidx.compose.material3.LinearProgressIndicator import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.DisposableEffect import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.runtime.setValue import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.platform.LocalContext import androidx.compose.ui.unit.dp import androidx.core.content.FileProvider import com.nianticspatial.nsdk.AsyncResult import com.nianticspatial.nsdk.NSDKSession import com.nianticspatial.nsdk.ScanSaveInfo import com.nianticspatial.nsdk.ScannerConfig import java.io.File import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.Job import kotlinx.coroutines.cancelAndJoin import kotlinx.coroutines.delay import kotlinx.coroutines.launch @Composable fun PlaybackCaptureScreen(nsdkSession: NSDKSession) { // Keep Android context, coroutine work, and acquired NSDK resources scoped to // this screen. In your app, these resources can instead be owned by a ViewModel // or another lifecycle-aware component. val context = LocalContext.current val coroutineScope = rememberCoroutineScope() val scanningSession = remember { nsdkSession.scanning.acquire() } val recordingExporter = remember { nsdkSession.recordingExporter.acquire() } // These Compose values drive the button labels, enabled states, progress bar, // saved-scan availability, and user-visible errors. var isRecording by remember { mutableStateOf(false) } var canStopCapture by remember { mutableStateOf(false) } var isSaving by remember { mutableStateOf(false) } var isExporting by remember { mutableStateOf(false) } var exportProgress by remember { mutableStateOf(0f) } var saveInfo by remember { mutableStateOf(null) } var errorMessage by remember { mutableStateOf(null) } // Cancel and join this screen's capture, save, and export work before closing // native resources. If your app owns these resources elsewhere, perform the // equivalent ordered cleanup in that lifecycle owner. DisposableEffect(Unit) { val screenJob = coroutineScope.coroutineContext[Job] onDispose { CoroutineScope(Dispatchers.IO).launch { screenJob?.cancelAndJoin() scanningSession.stop() scanningSession.close() recordingExporter.close() } } } fun startCapture() { // If your app already has a Start Capture handler, replace its existing // configure/start block with this flow instead of starting a second session. // Ignore duplicate taps while this screen is recording, saving, or exporting. // If your app has a ViewModel or another capture-state owner, perform the // equivalent state check there instead. if (isRecording || isSaving || isExporting) return // Clear results and messages from the previous capture before starting again. // Reset any additional app-specific scan state here as well. saveInfo = null canStopCapture = false errorMessage = null // Customize these values for the capture experience in your app. For example, // reuse your existing ScannerConfig or set basePath if scans should use a // non-default location. Configure the session before calling start(). val config = ScannerConfig().apply { useNsdkDepthsIfPlatformUnavailable = true enableRaycastVisualization = true enableVoxelVisualization = false } scanningSession.configure(config) scanningSession.start() Log.i("PlaybackCaptureScreen", "Capture start requested") // Updating Compose state changes the button to the waiting-for-frames state. // If capture state belongs to your ViewModel, update that state instead. isRecording = true // MultiDepth initialization or a GeographicLib download can delay the first // saved frame, so starting the session does not make stopping safe yet. // If your app owns background work in a ViewModel, move this polling coroutine // there, but keep the frame-count check before enabling the stop action. coroutineScope.launch { while (isRecording) { val frameCount = try { scanningSession.getRecordingInfo().frameCount } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Could not read frame count", exception) 0 } if (frameCount > 0) { // At least one frame is stored, so Stop Capture can now call save(). Log.i( "PlaybackCaptureScreen", "Capture ready to stop; frameCount=$frameCount" ) canStopCapture = true break } // Change the polling interval if your app needs a different UI cadence. delay(200) } } } suspend fun stopAndSaveCapture() { // Ignore duplicate stop taps and calls made outside an active recording. if (!isRecording || isSaving) return // Recheck the frame count at the save boundary. This protects callers other // than the button and prevents save() from receiving an empty recording. val frameCount = try { scanningSession.getRecordingInfo().frameCount } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Could not read frame count before save", exception) 0 } if (frameCount == 0) { // Discard the empty recording and restore the idle UI instead of saving it. scanningSession.stop() isRecording = false canStopCapture = false errorMessage = "Capture stopped before any frames were recorded." return } // Enter the saving state before starting native work so the controls cannot // submit another action. Move this state to your ViewModel if it owns capture. isSaving = true isRecording = false canStopCapture = false try { // save() finalizes the dataset on device and returns the information // required by the exporter. when (val result = scanningSession.save()) { is AsyncResult.Success -> saveInfo = result.value is AsyncResult.Error -> errorMessage = "Save failed: ${result.code}" is AsyncResult.Timeout -> errorMessage = "Save timed out." } } catch (exception: CancellationException) { throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Save failed with an exception", exception) errorMessage = "Save failed: ${exception.message ?: "Unknown error"}" } finally { // Stop the scanning session and restore the UI after every save outcome. scanningSession.stop() isSaving = false } } suspend fun exportCapture() { // Export requires the non-null path and scan ID returned by a successful save(). val scanInfo = saveInfo ?: return val scanDirPath = scanInfo.savePath val scanId = scanInfo.scanId if (scanDirPath == null || scanId == null) { Log.e("PlaybackCaptureScreen", "Saved scan information is incomplete") errorMessage = "The saved scan is missing its path or scan ID." return } // Reset export UI before starting. Replace these Compose assignments with // updates to your app's state owner when appropriate. isExporting = true exportProgress = 0f errorMessage = null Log.i("PlaybackCaptureScreen", "Export started for scanId=$scanId") try { // Create a playback-compatible archive from the saved scan. Keep // exportAsVideo false for playback datasets; adjust the timeout for your UX. val result = recordingExporter.export( scanDirPath = scanDirPath, scanId = scanId, exportAsVideo = false, timeoutMillis = 300_000, // The callback reports values from 0.0 to 1.0 for the progress indicator. onProgress = { progress -> exportProgress = progress } ) // Share the path returned by the exporter rather than constructing a path. // Replace shareArchive() if your app uploads or manages archives itself. when (result) { is AsyncResult.Success -> { Log.i("PlaybackCaptureScreen", "Export completed: ${result.value}") if (!shareArchive(context, result.value)) { errorMessage = "The archive was exported but could not be shared." } } is AsyncResult.Error -> { Log.e("PlaybackCaptureScreen", "Export failed: ${result.code}") errorMessage = "Export failed: ${result.code}" } is AsyncResult.Timeout -> { Log.w("PlaybackCaptureScreen", "Export timed out") errorMessage = "Export timed out." } } } catch (exception: CancellationException) { Log.i("PlaybackCaptureScreen", "Export cancelled") throw exception } catch (exception: Exception) { Log.e("PlaybackCaptureScreen", "Export failed with an exception", exception) errorMessage = "Export failed: ${exception.message ?: "Unknown error"}" } finally { // Restore the export controls after success, failure, timeout, or cancellation. isExporting = false } } // Render the capture, export, and progress UI for the full flow. Column( modifier = Modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(10.dp), horizontalAlignment = Alignment.CenterHorizontally ) { Button( // Disable the main action during save/export and until capture has // written at least one frame. enabled = !isSaving && !isExporting && (!isRecording || canStopCapture), onClick = { // The same control starts a new recording or saves the active one. // Split these into separate controls if that better matches your UI. if (!isRecording) { startCapture() } else { coroutineScope.launch { stopAndSaveCapture() } } } ) { // Derive the label from capture state so the user can see when stopping is safe. Text( when { isSaving -> "Saving..." !isRecording -> "Start Capture" canStopCapture -> "Stop Capture" else -> "Starting Capture..." } ) } // Show progress only while recordingExporter.export() is running. if (isExporting) { LinearProgressIndicator( progress = { exportProgress }, modifier = Modifier.fillMaxWidth().padding(horizontal = 20.dp) ) } // Offer export only after save() returns the path and ID of a saved scan. if (saveInfo != null && !isRecording && !isExporting) { Button( enabled = !isSaving, onClick = { coroutineScope.launch { exportCapture() } } ) { Text("Export Capture") } } // Replace this inline text with your app's snackbar, dialog, or error component. errorMessage?.let { message -> Text(message) } } } private fun shareArchive(context: Context, archivePath: String): Boolean { // Do not open the chooser if the exporter did not create the expected file. val file = File(archivePath) if (!file.exists()) { Log.e("PlaybackCaptureScreen", "Archive not found: $archivePath") return false } // Convert the private file path to a content URI that another app may read. // The FileProvider authority must match the declaration in AndroidManifest.xml. return runCatching { val uri = FileProvider.getUriForFile( context, "${context.packageName}.fileprovider", file ) // Grant the selected destination temporary read access to the archive. val shareIntent = Intent(Intent.ACTION_SEND).apply { type = "application/gzip" putExtra(Intent.EXTRA_STREAM, uri) addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION) } // Replace Android's chooser here if your product has a custom upload flow. context.startActivity(Intent.createChooser(shareIntent, "Share Capture")) Log.i("PlaybackCaptureScreen", "Share sheet opened for archive: $archivePath") true }.onFailure { exception -> Log.e("PlaybackCaptureScreen", "Could not open share sheet", exception) }.getOrDefault(false) } ``` The key parts of this example are: - `startCapture()` configures the scanning session, starts recording, and waits until stopping becomes safe. - `stopAndSaveCapture()` saves the recording and stores the returned `ScanSaveInfo` for export. - `exportCapture()` creates the playback `.tgz` archive and updates the progress bar while export runs. - `shareArchive(...)` opens Android's share sheet after export succeeds. ### Add to your app After validating the screen in the sample app: 1. Copy `PlaybackCaptureScreen.kt` from the sample app: ```text NsdkSamples/src/main/java/com/nianticspatial/nsdk/externalsamples/capture/PlaybackCaptureScreen.kt ``` into the package that contains your app's AR Compose UI. For example: ```text app/src/main/java/com/example/app/PlaybackCaptureScreen.kt ``` 2. In the first line of the copied file, replace `com.nianticspatial.nsdk.externalsamples.capture` with the package that matches its new location, for example `com.example.app`. 3. In the Kotlin file that renders your existing AR Compose UI, import the copied screen using your package name: ```kotlin // Replace this package with the package that contains your copied screen. import com.example.app.PlaybackCaptureScreen ``` 4. If your app does not already declare a `FileProvider`, add the following provider inside the `` block in your app module's `src/main/AndroidManifest.xml`: ```xml ``` If your app already has a provider, confirm that its authority matches `${context.packageName}.fileprovider` in `shareArchive(...)`. Otherwise, update the helper to use your existing authority. 5. Create `src/main/res/xml/file_paths.xml` in your app module, if it does not exist, and allow sharing from NSDK's default recording directory: ```xml ``` If your `ScannerConfig` sets a custom `basePath`, replace this entry with the narrowest matching path. Do not grant access to an entire storage root. 6. In your existing AR UI content, render the screen with the authenticated, frame-fed `NSDKSession` already used by the AR view: ```kotlin // Reuse the authenticated NSDKSession that your AR screen already updates with // live frames; do not create a second session only for recording. PlaybackCaptureScreen(nsdkSession = nsdkSession) ``` 7. Build and run your app on a physical ARCore-compatible device, then validate the complete lifecycle: 1. Open the AR screen that renders `PlaybackCaptureScreen`. 2. In Android Studio, open **View > Tool Windows > Logcat**, select the device and your app process, and enter `tag:PlaybackCaptureScreen` in the query field. 3. Tap **Start Capture** and confirm Logcat reports `Capture start requested`. 4. Move the device and wait until the control displays **Stop Capture**. Confirm Logcat reports `Capture ready to stop; frameCount=` with a value greater than zero. 5. Tap **Stop Capture** and confirm **Export Capture** appears after the save completes. 6. Tap **Export Capture** and confirm Logcat reports `Export started for scanId=`, followed by `Export completed:` with a `.tgz` path. 7. Confirm Android's share sheet opens and Logcat reports `Share sheet opened for archive:` with the same path. 8. Dismiss the share sheet, leave the AR screen, reopen it, and complete a second capture and export. This confirms that the first screen instance cancelled its work and released the acquired NSDK resources. 9. Confirm Logcat does not report `Could not read frame count`, `Save failed`, `Export failed`, or `Could not open share sheet`.