# Create playback datasets Source: https://www.nianticspatial.com/docs/nsdk/how-to/playback/create_playback_dataset/?platform=swift ## 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. The sample app is Niantic's working Swift 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](#swift-get-the-sample-source), then choose one of these independent workflows: - **[Capture](#swift-capture-sample):** Use the existing Capture screen to create a dataset quickly. - **[Recording API](#swift-api-record):** Build a tutorial controller 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 Swift instructions: - **Sample app** means Niantic's downloaded `nsdk-samples-swift` project. - **Tutorial controller** means the `PlaybackCaptureViewController` you create. - **Your app** means the application where you will integrate the completed recording flow. Swift Capture sample recording and exporting a playback dataset. ## Get the sample app Both workflows use the public [`nsdk-samples-swift`](https://github.com/nianticspatial/nsdk-samples-swift) repository. Use a Mac with Xcode 16 or later and a physical ARKit-capable device running iOS 18 or later. Get and open the sample source: 1. In Terminal, clone the repository: ```bash git clone https://github.com/nianticspatial/nsdk-samples-swift.git ``` Alternatively, select **Code > Download ZIP** on GitHub, then extract the ZIP. 2. In Xcode, select **File > Open**, then select `/nsdk-samples-swift/NsdkSamples/NsdkSamples.xcworkspace`. 3. In Xcode, select the `NsdkSamples` scheme. 4. Select the `NsdkSamples` target, open **Signing & Capabilities**, and choose your development team if Xcode requests one. 5. Wait for package resolution and indexing to finish. ## Record with Capture The Capture screen is the fastest way to create a playback dataset on iOS without building your own recording interface. ### Run Capture 1. Connect and select a physical iOS device in Xcode. 2. Select **Product > Run**. 3. On the device, grant camera and location access when prompted. 4. Complete the sample app's sign-in flow. 5. Open **Capture** from the sample list. 6. Tap **Start Capture**. ### Record the environment Move the device through the environment while keeping it in portrait orientation. Hold it steadily enough for the AR session to track and for capture frames to be saved. After tapping **Start Capture**, wait for the scan visualization to begin updating and record the environment for several seconds before tapping **Stop Capture**. This gives the sample time to begin saving frames. ### Export the dataset 1. Tap **Stop Capture** after the app has recorded the environment. 2. Wait while the sample saves and exports the recording. 3. In the iOS share sheet, save the resulting `.tgz` archive to Files, send it with AirDrop, or share it with another app. ## Record with the API The Swift API gives you control over the recording UI, capture state, frame-count gate, export progress, and sharing behavior. This workflow uses the sample app as a runnable development environment. You will build a separate UIKit controller, validate each stage on a device, and then move the recording pieces into your own AR view controller. The API walkthrough contains these sections: 1. [Capture implementation overview](#swift-capture-implementation-overview) 2. [Prepare the sample app](#swift-prepare-the-sample-app) 3. [Create the tutorial controller](#swift-create-the-tutorial-controller) 4. [Add capture controls](#swift-add-capture-controls) 5. [Start capture](#swift-start-capture) 6. [Stop and save](#swift-stop-and-save) 7. [Export the archive](#swift-export-the-archive) 8. [Share the archive](#swift-share-the-archive) 9. [Retrieve and verify the recording](#swift-retrieve-and-verify-the-recording) 10. [View the complete PlaybackCaptureViewController](#swift-complete-api-example) 11. [Add to your app](#swift-add-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 controller: | Sample file | Responsibility | | --- | --- | | `NsdkSamples/ViewControllers/CaptureViewController.swift` | Owns the sample capture controls, recording state, save/export flow, and share sheet. | | `NsdkSamples/AR/ARManager.swift` | Provides the authenticated `NSDKSession`, camera view, AR-session lifecycle, and live frame updates. | | `NsdkSamples/ViewControllers/MainViewController.swift` | Routes from the sample list to each sample view controller. | The tutorial creates a separate `PlaybackCaptureViewController.swift` so Niantic's Capture reference implementation remains unchanged. When the finished controller moves into an app, that app must provide an authenticated `NSDKSession` that is already receiving live AR frames, camera and location permissions, and product-specific archive sharing or upload behavior. Standalone development or internal-test builds can use a developer token from **Credentials > Developer Tokens** in [Scaniverse web](https://scaniverse.nianticspatial.com/signin). 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 Prepare the device before adding the tutorial controller: 1. Build and run `NsdkSamples` on a physical device. 2. Grant camera and location access when prompted. 3. Complete the sample app's sign-in flow. 4. Open **Capture** and confirm that the camera view appears. 5. Return to the sample list without starting a recording. The sample app retains these permissions and authentication for the implementation steps that follow. ### Create the tutorial controller Create `PlaybackCaptureViewController.swift` in the sample app's `NsdkSamples/ViewControllers` folder. The project uses a synchronized folder, so Xcode includes the new file in the app target automatically. The tutorial controller uses `ARManager` from `NsdkSamples/AR/ARManager.swift` for the authenticated `NSDKSession`, camera view, AR-session lifecycle, and live frame updates. It creates its own recording flow instead of modifying Niantic's `CaptureViewController.swift` reference implementation. #### Expand to create PlaybackCaptureViewController.swift with its initial state and placeholders Add the following compiling skeleton to `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`: ```swift import NSDK import UIKit @MainActor final class PlaybackCaptureViewController: UIViewController { // ARManager belongs to Niantic's sample app. It supplies the authenticated, // frame-fed NSDKSession and the camera view used to validate this controller. private let arManager: ARManager // Keep recording resources and state with this screen. Move them to your // app's model layer if that layer owns the recording lifecycle. private var scanningSession: NSDKScanningSession? private var isCapturing = false private var canStopCapture = false private var isSaving = false private var isExporting = false private var frameMonitorTask: Task? private var captureTask: Task? // Replace these UIKit controls with your design system while preserving the // state checks that enable Stop and report export progress. private let captureButton = UIButton(type: .system) private let progressView = UIProgressView(progressViewStyle: .default) private let statusLabel = UILabel() // The sample app injects ARManager here. In your app, keep the AR // dependencies already owned by the existing AR view controller. init(arManager: ARManager) { self.arManager = arManager super.init(nibName: nil, bundle: nil) } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } override func viewDidLoad() { super.viewDidLoad() title = "Playback Capture" view.backgroundColor = .black // Keep the sample app's live camera view behind the tutorial controls. // Your app should keep its existing AR view instead of copying NSDKView. arManager.nsdkView.setup(in: view) setupControls() prepareCapture() } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) // Start the sample app's AR session when this screen becomes visible. // Keep your app's existing AR-session start call where it already runs. arManager.startSession() } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) // Cancel this screen's work before stopping its scanning session. frameMonitorTask?.cancel() captureTask?.cancel() scanningSession?.stop() } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) // Stop the sample app's AR session after leaving this screen. Keep your // app's existing AR-session stop call in its current lifecycle method. arManager.stopSession() } private func prepareCapture() { guard scanningSession == nil else { return } // Acquire and configure once for this screen. Reuse your existing // configuration here if your app already owns one. // Replace arManager.nsdkSession with the authenticated, frame-fed // NSDKSession already owned by your AR screen. let session = arManager.nsdkSession.acquireScanningSession() // Customize these values for your recording experience. Preserve your // existing NSDKScanningSession configuration when integrating this flow. var config = NSDKScanningSession.Configuration() config.enableRaycastVisualization = true config.enableVoxelVisualization = false config.generateDepthsIfLidarUnavailable = true do { try session.configure(with: config) scanningSession = session print("PlaybackCaptureViewController: scanning session configured") } catch { statusLabel.text = "Could not configure capture: \(error.localizedDescription)" captureButton.isEnabled = false print("PlaybackCaptureViewController: configuration failed: \(error)") } } private func setupControls() { // Placeholder: replaced in "Add capture controls." } private func updateCaptureButton() { // Placeholder: replaced in "Add capture controls." } @objc private func handleCaptureButtonTap() { // Placeholder: replaced in "Add capture controls." } private func startCapture() { // Placeholder: replaced in "Start capture." } private func stopAndSaveCapture() { // Placeholder: replaced in "Stop and save." } private func resetCaptureUI() { // Placeholder: replaced in "Stop and save." } private func exportCapture( saveInfo: NSDKScanningSession.SaveInfo ) async throws { // Placeholder: replaced in "Export the archive." } private func presentShareSheet(for archivePath: String) { // Placeholder: replaced in "Share the archive." } } ``` Connect the tutorial controller to the sample app: 1. Open `NsdkSamples/ViewControllers/MainViewController.swift`. 2. In the `menuItems` array, replace only: ```swift MenuItem(title: "Capture") { CaptureViewController(arManager: $0) }, ``` with: ```swift // Temporarily route Capture to the tutorial-owned controller. MenuItem(title: "Capture") { PlaybackCaptureViewController(arManager: $0) }, ``` Keep this routing change through the remaining API steps. The original `CaptureViewController.swift` remains unchanged as reference code. **Validate this step:** 1. Select **Product > Build** and confirm the app compiles. 2. Run `NsdkSamples` and open **Capture**. 3. Confirm the camera view opens with the title **Playback Capture**. 4. In Xcode's debug console, confirm `PlaybackCaptureViewController: scanning session configured` appears. The screen does not display capture controls yet. The next step adds them. ### Add capture controls In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, locate these three placeholder methods: ```swift private func setupControls() { // Placeholder: replaced in "Add capture controls." } private func updateCaptureButton() { // Placeholder: replaced in "Add capture controls." } @objc private func handleCaptureButtonTap() { // Placeholder: replaced in "Add capture controls." } ``` In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, replace all three placeholder method definitions with the following implementations: #### Expand to replace the Swift capture-control methods ```swift private func setupControls() { // Use the label for capture and export errors. Replace it with your app's // alert, banner, or other status UI if needed. statusLabel.textColor = .white statusLabel.numberOfLines = 0 statusLabel.textAlignment = .center statusLabel.translatesAutoresizingMaskIntoConstraints = false view.addSubview(statusLabel) // Hide progress until export starts. Bind the export callback to your // existing progress UI if your app does not use UIProgressView. progressView.isHidden = true progressView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(progressView) // Connect your app's existing capture action to // handleCaptureButtonTap() instead of creating a second button. captureButton.setTitle("Start Capture", for: .normal) captureButton.setTitleColor(.white, for: .normal) captureButton.backgroundColor = .systemBlue captureButton.layer.cornerRadius = 8 captureButton.titleLabel?.font = .boldSystemFont(ofSize: 16) captureButton.addTarget( self, action: #selector(handleCaptureButtonTap), for: .touchUpInside ) captureButton.translatesAutoresizingMaskIntoConstraints = false view.addSubview(captureButton) // These constraints are sample UI. Use your app's existing layout when // moving the recording flow into its AR screen. NSLayoutConstraint.activate([ captureButton.centerXAnchor.constraint(equalTo: view.centerXAnchor), captureButton.bottomAnchor.constraint( equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -20 ), captureButton.widthAnchor.constraint(equalToConstant: 200), captureButton.heightAnchor.constraint(equalToConstant: 44), progressView.leadingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.leadingAnchor, constant: 20 ), progressView.trailingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.trailingAnchor, constant: -20 ), progressView.bottomAnchor.constraint( equalTo: captureButton.topAnchor, constant: -16 ), statusLabel.leadingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.leadingAnchor, constant: 20 ), statusLabel.trailingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.trailingAnchor, constant: -20 ), statusLabel.bottomAnchor.constraint( equalTo: progressView.topAnchor, constant: -12 ), ]) } private func updateCaptureButton() { // Derive the control state from the recording lifecycle. Preserve the // canStopCapture gate if your app renders this state elsewhere. let title: String if isSaving { title = "Saving..." } else if isExporting { title = "Exporting..." } else if !isCapturing { title = "Start Capture" } else if canStopCapture { title = "Stop Capture" } else { title = "Starting Capture..." } captureButton.setTitle(title, for: .normal) captureButton.isEnabled = !isSaving && !isExporting && (!isCapturing || canStopCapture) } @objc private func handleCaptureButtonTap() { // If your app already has a capture-button action, call the matching // start or stop method from that action instead of copying this target. if isCapturing { stopAndSaveCapture() } else { startCapture() } } ``` **Validate this step:** 1. Build and run `NsdkSamples`. 2. Open **Capture**. 3. Confirm **Start Capture** appears and the progress indicator is not displayed. The button does not start recording yet because `startCapture()` is still a placeholder. ### Start capture In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, locate the placeholder `startCapture()` method and replace the entire method with the following code. It starts the scanning session, polls the recorded frame count, and enables the stop action only after NSDK has saved at least one frame: #### Expand to replace the Swift start-capture method ```swift private func startCapture() { // Ignore duplicate taps and requests made while save or export owns the // session. Apply the same guard in your app's capture state owner. guard let scanningSession, !isCapturing, !isSaving, !isExporting else { return } // Clear messages and reset the frame gate before requesting a recording. statusLabel.text = "" canStopCapture = false isCapturing = true updateCaptureButton() // start() requests capture, but capture is not ready to stop until // recordingInfo() reports at least one saved frame. scanningSession.start() print("PlaybackCaptureViewController: capture start requested") // Poll until NSDK confirms that it has saved a frame. Keep this work in // your model layer instead if that layer owns capture state. frameMonitorTask?.cancel() frameMonitorTask = Task { @MainActor [weak self] in guard let self else { return } while isCapturing && !Task.isCancelled { let frameCount = scanningSession.recordingInfo().frameCount if frameCount > 0 { canStopCapture = true updateCaptureButton() print( "PlaybackCaptureViewController: capture ready to stop; " + "frameCount=\(frameCount)" ) return } try? await Task.sleep(nanoseconds: 200_000_000) } } } ``` 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 `recordingInfo().frameCount` is greater than zero. Until then, keep the stop action disabled. **Validate this step:** 1. Build and run `NsdkSamples`, then open **Capture**. 2. Tap **Start Capture**. 3. Move the device until the button changes to **Stop Capture**. 4. In Xcode's debug console, confirm: ```text PlaybackCaptureViewController: capture start requested PlaybackCaptureViewController: capture ready to stop; frameCount= ``` The second message must end with a value greater than zero. ### Stop and save In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, locate the placeholder `stopAndSaveCapture()` method and replace the entire method with the following code. It rechecks the frame count, saves the recording, and starts export after saving succeeds. The disabled button is the primary frame-count gate, but this method checks again immediately before `saveCurrentScan()` so other callers cannot submit an empty recording: #### Expand to replace the Swift stop-and-save methods ```swift private func stopAndSaveCapture() { // Accept Stop only after the frame monitor opens the gate. Preserve this // guard even if your app exposes Stop through a different control. guard let scanningSession, isCapturing, canStopCapture, !isSaving else { return } // Recheck at the save boundary so callers other than the button cannot // pass an empty recording to saveCurrentScan(). guard scanningSession.recordingInfo().frameCount > 0 else { scanningSession.stop() isCapturing = false canStopCapture = false statusLabel.text = "Capture stopped before any frames were recorded." updateCaptureButton() return } // Disable recording controls before beginning asynchronous save work. frameMonitorTask?.cancel() frameMonitorTask = nil isCapturing = false canStopCapture = false isSaving = true updateCaptureButton() print("PlaybackCaptureViewController: save started") captureTask?.cancel() captureTask = Task { @MainActor [weak self] in guard let self else { return } do { // Save the recording before creating its playback archive. let saveInfo = try await scanningSession.saveCurrentScan( timeout: 10, pollingInterval: 0.1 ) scanningSession.stop() isSaving = false updateCaptureButton() print( "PlaybackCaptureViewController: save completed; " + "scanId=\(saveInfo.scanId)" ) try await exportCapture(saveInfo: saveInfo) } catch is CancellationError { scanningSession.stop() resetCaptureUI() print("PlaybackCaptureViewController: capture work cancelled") } catch { scanningSession.stop() statusLabel.text = "Save or export failed: \(error.localizedDescription)" resetCaptureUI() print("PlaybackCaptureViewController: save or export failed: \(error)") } } } ``` Immediately after `stopAndSaveCapture()` in the same file, locate the placeholder `resetCaptureUI()` method and replace that entire method with the following code. It returns every capture and export flag to its idle state after cancellation or an error: ```swift private func resetCaptureUI() { // Return every transient flag to idle after cancellation or an error. // Apply the equivalent reset to your app's capture state owner. isCapturing = false canStopCapture = false isSaving = false isExporting = false progressView.isHidden = true updateCaptureButton() } ``` **Validate this step:** 1. Build and run `NsdkSamples`, then open **Capture**. 2. Start capture and wait for **Stop Capture**. 3. Tap **Stop Capture**. 4. In Xcode's debug console, confirm `PlaybackCaptureViewController: save started` and `PlaybackCaptureViewController: save completed; scanId=` appear. 5. Confirm the button returns to **Start Capture**. Export is still a placeholder and is added in the next step. ### Export the archive In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, locate the placeholder `exportCapture(saveInfo:)` method and replace the entire method with the following code. Use the path and scan ID returned by `saveCurrentScan()` rather than constructing a storage path: #### Expand to replace the Swift export method ```swift private func exportCapture(saveInfo: NSDKScanningSession.SaveInfo) async throws { // Pass the values returned by saveCurrentScan() to the exporter instead // of constructing a scan ID or storage path. // Replace arManager.nsdkSession with the same NSDKSession used by // prepareCapture() when moving this code into your app. let exporter = arManager.nsdkSession.acquireRecordingExporter() isExporting = true progressView.progress = 0 progressView.isHidden = false updateCaptureButton() print( "PlaybackCaptureViewController: export started; " + "scanId=\(saveInfo.scanId)" ) // Keep exportAsVideo false for a playback dataset. Adjust the timeout // for your product, and map progressCallback to its progress UI. let archivePath = try await exporter.export( scanDirPath: saveInfo.path, scanId: saveInfo.scanId, exportAsVideo: false, pollingInterval: 0.1, timeout: 300, progressCallback: { [weak self] progress in Task { @MainActor in self?.progressView.setProgress(progress, animated: true) } } ) isExporting = false progressView.setProgress(1, animated: true) progressView.isHidden = true updateCaptureButton() print("PlaybackCaptureViewController: export completed: \(archivePath)") // Use the returned archive path for the next product-specific action. presentShareSheet(for: archivePath) } ``` By default, NSDK saves recordings under the app container's `Documents/scankit/` directory. If you set `NSDKScanningSession.Configuration.path`, the saved scan and archive use that configured location instead. The successful export result contains the actual `.tgz` path; use that returned value for sharing or upload. **Validate this step:** 1. Build and run `NsdkSamples` and complete a capture. 2. In Xcode's debug console, confirm `PlaybackCaptureViewController: export started; scanId=` is followed by `PlaybackCaptureViewController: export completed:` and a `.tgz` path. 3. Confirm no share sheet appears yet because `presentShareSheet(for:)` is still a placeholder. ### Share the archive In `NsdkSamples/ViewControllers/PlaybackCaptureViewController.swift`, locate the placeholder `presentShareSheet(for:)` method and replace the entire method with the following code. It verifies the exporter result before presenting the standard iOS share sheet: #### Expand to replace the Swift share method ```swift private func presentShareSheet(for archivePath: String) { // Verify the exporter result before presenting it to another app. guard FileManager.default.fileExists(atPath: archivePath) else { statusLabel.text = "The archive was exported but could not be found." print("PlaybackCaptureViewController: archive not found: \(archivePath)") return } // Replace UIActivityViewController with your upload or storage flow if // your product does not share archives through the system share sheet. let fileURL = URL(fileURLWithPath: archivePath) let shareController = UIActivityViewController( activityItems: [fileURL], applicationActivities: nil ) present(shareController, animated: true) print( "PlaybackCaptureViewController: share sheet opened for archive: " + archivePath ) } ``` **Validate this step:** 1. Build and run `NsdkSamples` and complete a capture. 2. Wait for export to finish and confirm the iOS share sheet opens. 3. In Xcode's debug console, confirm `PlaybackCaptureViewController: share sheet opened for archive:` contains the same path reported by `export completed:`. 4. Save the archive to Files or dismiss the share sheet, then confirm the app returns to Capture without an error message. ### Retrieve and verify the recording Enable Finder access to the sample app's Documents directory, copy the exported archive to the Mac, and confirm that it contains recorded frames: 1. In Xcode's project navigator, select `NsdkSamples/NsdkSamples/Info.plist`. From the menu bar, select **Editor > Open As > Source Code**. 2. Before the closing `` element, confirm that both of the following keys are present. The downloaded sample app already contains `UIFileSharingEnabled`; add `LSSupportsOpeningDocumentsInPlace` if it is missing. When you apply this workflow to your own app, add either missing key so that its `Info.plist` contains both: ```xml UIFileSharingEnabled LSSupportsOpeningDocumentsInPlace ``` 3. Build and run `NsdkSamples` again so the installed app contains the updated `Info.plist`. 4. Keep the device connected and unlocked. In Finder, select the device in the sidebar, select **Files**, expand **NSDK Samples**, and drag the `scankit` folder to the Mac. 5. In the copied `scankit` folder, open the scan-ID directory from the `export completed:` path and locate `chunk_0.tgz`. 6. Select `chunk_0.tgz`, then select **File > Open** from the Finder menu bar. macOS Archive Utility extracts the recording beside the `.tgz` file. 7. Open the extracted directory and confirm that it contains `capture.json` and `frame_*.jpg` files. 8. Select `capture.json`, then select **File > Open With > TextEdit** from the Finder menu bar. In TextEdit, select **Edit > Find > Find**, then search for `"frameCount"`. Confirm that the value of this top-level property is greater than zero. 9. Confirm that the frame image sequence starts at `frame_00000000.jpg` and ends at `frameCount - 1`. For example, a `frameCount` of `23` corresponds to `frame_00000000.jpg` through `frame_00000022.jpg`. 10. Select several `frame_*.jpg` files and select **File > Open**. Confirm that Preview displays 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 PlaybackCaptureViewController The expandable section contains the complete `PlaybackCaptureViewController.swift` assembled in the preceding steps. Use it to check your completed controller, 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 `CaptureViewController.swift` is a separate sample-app implementation and does not correspond line-for-line with these steps. #### Expand to reveal PlaybackCaptureViewController.swift ```swift import NSDK import UIKit @MainActor final class PlaybackCaptureViewController: UIViewController { // ARManager belongs to Niantic's sample app. It supplies the authenticated, // frame-fed NSDKSession and the camera view used to validate this controller. private let arManager: ARManager // Keep recording resources and state with this screen. Move them to your // app's model layer if that layer owns the recording lifecycle. private var scanningSession: NSDKScanningSession? private var isCapturing = false private var canStopCapture = false private var isSaving = false private var isExporting = false private var frameMonitorTask: Task? private var captureTask: Task? // Replace these UIKit controls with your design system while preserving the // state checks that enable Stop and report export progress. private let captureButton = UIButton(type: .system) private let progressView = UIProgressView(progressViewStyle: .default) private let statusLabel = UILabel() // The sample app injects ARManager here. In your app, keep the AR // dependencies already owned by the existing AR view controller. init(arManager: ARManager) { self.arManager = arManager super.init(nibName: nil, bundle: nil) } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } override func viewDidLoad() { super.viewDidLoad() title = "Playback Capture" view.backgroundColor = .black // Keep the sample app's live camera view behind the tutorial controls. // Your app should keep its existing AR view instead of copying NSDKView. arManager.nsdkView.setup(in: view) setupControls() prepareCapture() } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) // Start the sample app's AR session when this screen becomes visible. // Keep your app's existing AR-session start call where it already runs. arManager.startSession() } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) // Cancel this screen's work before stopping its scanning session. frameMonitorTask?.cancel() captureTask?.cancel() scanningSession?.stop() } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) // Stop the sample app's AR session after leaving this screen. Keep your // app's existing AR-session stop call in its current lifecycle method. arManager.stopSession() } private func prepareCapture() { guard scanningSession == nil else { return } // Acquire and configure once for this screen. Reuse your existing // configuration here if your app already owns one. // Replace arManager.nsdkSession with the authenticated, frame-fed // NSDKSession already owned by your AR screen. let session = arManager.nsdkSession.acquireScanningSession() // Customize these values for your recording experience. Preserve your // existing NSDKScanningSession configuration when integrating this flow. var config = NSDKScanningSession.Configuration() config.enableRaycastVisualization = true config.enableVoxelVisualization = false config.generateDepthsIfLidarUnavailable = true do { try session.configure(with: config) scanningSession = session print("PlaybackCaptureViewController: scanning session configured") } catch { statusLabel.text = "Could not configure capture: \(error.localizedDescription)" captureButton.isEnabled = false print("PlaybackCaptureViewController: configuration failed: \(error)") } } private func setupControls() { // Use the label for capture and export errors. Replace it with your // app's alert, banner, or other status UI if needed. statusLabel.textColor = .white statusLabel.numberOfLines = 0 statusLabel.textAlignment = .center statusLabel.translatesAutoresizingMaskIntoConstraints = false view.addSubview(statusLabel) // Hide progress until export starts. Bind the export callback to your // existing progress UI if your app does not use UIProgressView. progressView.isHidden = true progressView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(progressView) // Connect your app's existing capture action to // handleCaptureButtonTap() instead of creating a second button. captureButton.setTitle("Start Capture", for: .normal) captureButton.setTitleColor(.white, for: .normal) captureButton.backgroundColor = .systemBlue captureButton.layer.cornerRadius = 8 captureButton.titleLabel?.font = .boldSystemFont(ofSize: 16) captureButton.addTarget( self, action: #selector(handleCaptureButtonTap), for: .touchUpInside ) captureButton.translatesAutoresizingMaskIntoConstraints = false view.addSubview(captureButton) // These constraints are sample UI. Use your app's existing layout when // moving the recording flow into its AR screen. NSLayoutConstraint.activate([ captureButton.centerXAnchor.constraint(equalTo: view.centerXAnchor), captureButton.bottomAnchor.constraint( equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -20 ), captureButton.widthAnchor.constraint(equalToConstant: 200), captureButton.heightAnchor.constraint(equalToConstant: 44), progressView.leadingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.leadingAnchor, constant: 20 ), progressView.trailingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.trailingAnchor, constant: -20 ), progressView.bottomAnchor.constraint( equalTo: captureButton.topAnchor, constant: -16 ), statusLabel.leadingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.leadingAnchor, constant: 20 ), statusLabel.trailingAnchor.constraint( equalTo: view.safeAreaLayoutGuide.trailingAnchor, constant: -20 ), statusLabel.bottomAnchor.constraint( equalTo: progressView.topAnchor, constant: -12 ), ]) } private func updateCaptureButton() { // Derive the control state from the recording lifecycle. Preserve the // canStopCapture gate if your app renders this state elsewhere. let title: String if isSaving { title = "Saving..." } else if isExporting { title = "Exporting..." } else if !isCapturing { title = "Start Capture" } else if canStopCapture { title = "Stop Capture" } else { title = "Starting Capture..." } captureButton.setTitle(title, for: .normal) captureButton.isEnabled = !isSaving && !isExporting && (!isCapturing || canStopCapture) } @objc private func handleCaptureButtonTap() { // If your app already has a capture-button action, call the matching // start or stop method from that action instead of copying this target. if isCapturing { stopAndSaveCapture() } else { startCapture() } } private func startCapture() { // Ignore duplicate taps and requests made while save or export owns the // session. Apply the same guard in your app's capture state owner. guard let scanningSession, !isCapturing, !isSaving, !isExporting else { return } // Clear messages and reset the frame gate before requesting a recording. statusLabel.text = "" canStopCapture = false isCapturing = true updateCaptureButton() // start() requests capture, but capture is not ready to stop until // recordingInfo() reports at least one saved frame. scanningSession.start() print("PlaybackCaptureViewController: capture start requested") // Poll until NSDK confirms that it has saved a frame. Keep this work in // your model layer instead if that layer owns capture state. frameMonitorTask?.cancel() frameMonitorTask = Task { @MainActor [weak self] in guard let self else { return } while isCapturing && !Task.isCancelled { let frameCount = scanningSession.recordingInfo().frameCount if frameCount > 0 { canStopCapture = true updateCaptureButton() print( "PlaybackCaptureViewController: capture ready to stop; " + "frameCount=\(frameCount)" ) return } try? await Task.sleep(nanoseconds: 200_000_000) } } } private func stopAndSaveCapture() { // Accept Stop only after the frame monitor opens the gate. Preserve this // guard even if your app exposes Stop through a different control. guard let scanningSession, isCapturing, canStopCapture, !isSaving else { return } // Recheck at the save boundary so callers other than the button cannot // pass an empty recording to saveCurrentScan(). guard scanningSession.recordingInfo().frameCount > 0 else { scanningSession.stop() isCapturing = false canStopCapture = false statusLabel.text = "Capture stopped before any frames were recorded." updateCaptureButton() return } // Disable recording controls before beginning asynchronous save work. frameMonitorTask?.cancel() frameMonitorTask = nil isCapturing = false canStopCapture = false isSaving = true updateCaptureButton() print("PlaybackCaptureViewController: save started") captureTask?.cancel() captureTask = Task { @MainActor [weak self] in guard let self else { return } do { // Save the recording before creating its playback archive. let saveInfo = try await scanningSession.saveCurrentScan( timeout: 10, pollingInterval: 0.1 ) scanningSession.stop() isSaving = false updateCaptureButton() print( "PlaybackCaptureViewController: save completed; " + "scanId=\(saveInfo.scanId)" ) try await exportCapture(saveInfo: saveInfo) } catch is CancellationError { scanningSession.stop() resetCaptureUI() print("PlaybackCaptureViewController: capture work cancelled") } catch { scanningSession.stop() statusLabel.text = "Save or export failed: \(error.localizedDescription)" resetCaptureUI() print("PlaybackCaptureViewController: save or export failed: \(error)") } } } private func resetCaptureUI() { // Return every transient flag to idle after cancellation or an error. // Apply the equivalent reset to your app's capture state owner. isCapturing = false canStopCapture = false isSaving = false isExporting = false progressView.isHidden = true updateCaptureButton() } private func exportCapture(saveInfo: NSDKScanningSession.SaveInfo) async throws { // Pass the values returned by saveCurrentScan() to the exporter instead // of constructing a scan ID or storage path. // Replace arManager.nsdkSession with the same NSDKSession used by // prepareCapture() when moving this code into your app. let exporter = arManager.nsdkSession.acquireRecordingExporter() isExporting = true progressView.progress = 0 progressView.isHidden = false updateCaptureButton() print( "PlaybackCaptureViewController: export started; " + "scanId=\(saveInfo.scanId)" ) // Keep exportAsVideo false for a playback dataset. Adjust the timeout // for your product, and map progressCallback to its progress UI. let archivePath = try await exporter.export( scanDirPath: saveInfo.path, scanId: saveInfo.scanId, exportAsVideo: false, pollingInterval: 0.1, timeout: 300, progressCallback: { [weak self] progress in Task { @MainActor in self?.progressView.setProgress(progress, animated: true) } } ) isExporting = false progressView.setProgress(1, animated: true) progressView.isHidden = true updateCaptureButton() print("PlaybackCaptureViewController: export completed: \(archivePath)") // Use the returned archive path for the next product-specific action. presentShareSheet(for: archivePath) } private func presentShareSheet(for archivePath: String) { // Verify the exporter result before presenting it to another app. guard FileManager.default.fileExists(atPath: archivePath) else { statusLabel.text = "The archive was exported but could not be found." print("PlaybackCaptureViewController: archive not found: \(archivePath)") return } // Replace UIActivityViewController with your upload or storage flow if // your product does not share archives through the system share sheet. let fileURL = URL(fileURLWithPath: archivePath) let shareController = UIActivityViewController( activityItems: [fileURL], applicationActivities: nil ) present(shareController, animated: true) print( "PlaybackCaptureViewController: share sheet opened for archive: " + archivePath ) } } ``` ### Add to your app `ARManager` is part of Niantic's sample app; your app does not need to create an equivalent class. It supplies three concrete dependencies during tutorial validation: | Sample code | Use in your app | | --- | --- | | `arManager.nsdkSession` | Reuse the authenticated `NSDKSession` that your AR screen already updates with live frames. | | `arManager.nsdkView.setup(in: view)` | Keep your AR screen's existing camera or rendering view setup. | | `arManager.startSession()` and `stopSession()` | Keep your AR screen's existing AR-session lifecycle. | Move the completed recording flow into your existing UIKit AR view controller: 1. Copy the recording state, controls, and methods from `PlaybackCaptureViewController` into the view controller that already owns your AR screen. Do not copy the `arManager` property, initializer, or AR-session lifecycle methods. 2. In `prepareCapture()`, replace: ```swift let session = arManager.nsdkSession.acquireScanningSession() ``` with: ```swift // Reuse the authenticated, frame-fed session already owned by this screen. let session = nsdkSession.acquireScanningSession() ``` 3. In `exportCapture(saveInfo:)`, replace: ```swift let exporter = arManager.nsdkSession.acquireRecordingExporter() ``` with: ```swift let exporter = nsdkSession.acquireRecordingExporter() ``` 4. Call `setupControls()` and `prepareCapture()` from your existing `viewDidLoad()` after its AR view is installed. 5. Add the following cleanup to your existing `viewWillDisappear(_:)` while preserving its current AR-session cleanup: ```swift frameMonitorTask?.cancel() captureTask?.cancel() scanningSession?.stop() ``` 6. Build and run the app on a supported physical device, then validate the complete lifecycle: 1. Open the AR screen and the Xcode debug console. 2. Tap **Start Capture** and confirm `capture start requested` appears. 3. Wait for **Stop Capture** and confirm `capture ready to stop; frameCount=` reports a value greater than zero. 4. Tap **Stop Capture** and confirm the save-started and save-completed messages appear. 5. Confirm the export-completed and share-sheet messages contain the same `.tgz` path. 6. Dismiss the share sheet, leave the AR screen, reopen it, and complete a second capture and export. This confirms the first controller cancelled its work and stopped its scanning session. 7. Confirm the console does not report `configuration failed`, `save or export failed`, or `archive not found`.