<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Cinematic",
  "identifier" : "/documentation/Cinematic/CNScript-1ispe",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Cinematic"
    ],
    "preciseIdentifier" : "s:9Cinematic8CNScriptC"
  },
  "title" : "CNScript"
}
-->

# CNScript

A collection of focus decisions, focus transitions, detections, and detection tracks associated with a movie captured in Cinematic mode and methods to change them.

```
final class CNScript
```

## Overview

The Cinematic script provides thread-safe access to information about the focus decisions made in the original recorded Cinematic movie. The script supports changing those decisions and obtaining updated information about where to focus each frame. You can snapshot changes to a script and later reload them.

> Tip:
> Look up what you need up front, outside your critical code, and pass the immutable results to where it’s needed. That way, you’re not blocked when you access the information inside the rendering portion of your code.

## Topics

### Structures

[`struct Changes`](/documentation/Cinematic/CNScript-1ispe/Changes)

An object that represents a snapshot of the changes made to a movie script, including the added user decisions and detection tracks.

[`struct Frame`](/documentation/Cinematic/CNScript-1ispe/Frame)

An object that represents what to focus on, and where to focus, in a given movie frame.

### Initializers

[`init(asset: AVAsset, changes: CNScript.Changes?, progress: Progress?) async throws`](/documentation/Cinematic/CNScript-1ispe/init(asset:changes:progress:))

Creates a Cinematic script based on a movie and applying changes to the movie.

### Instance Properties

[`var addedDetectionTracks: [CNDetectionTrack]`](/documentation/Cinematic/CNScript-1ispe/addedDetectionTracks)

An array of the detection tracks added since recording the original Cinematic movie.

[`var fNumber: Float`](/documentation/Cinematic/CNScript-1ispe/fNumber)

The f-stop value which inversely affects the aperture used to render the Cinematic image.

[`var timeRange: CMTimeRange`](/documentation/Cinematic/CNScript-1ispe/timeRange)

The time range of the selected track.

### Instance Methods

[`func addDetectionTrack(CNDetectionTrack) -> CNDetectionID`](/documentation/Cinematic/CNScript-1ispe/addDetectionTrack(_:))

Adds a user-created detection track.

[`func addUserDecision(CNDecision) -> Bool`](/documentation/Cinematic/CNScript-1ispe/addUserDecision(_:))

Adds a new user decision, and replaces an existing user decision if the times are identical.

[`func baseDecisions(in: CMTimeRange) -> [CNDecision]`](/documentation/Cinematic/CNScript-1ispe/baseDecisions(in:))

All base decisions made automatically during recording in the given time range.

[`func changes() -> CNScript.Changes`](/documentation/Cinematic/CNScript-1ispe/changes())

Changes made since recording the Cinematic asset.

[`func changes(trimmedBy: CMTimeRange) -> CNScript.Changes`](/documentation/Cinematic/CNScript-1ispe/changes(trimmedBy:))

Changes trimmed and time range shifted to start at zero.

[`func decision(after: CMTime) -> CNDecision?`](/documentation/Cinematic/CNScript-1ispe/decision(after:))

The decision that occurs after the given time.

[`func decision(at: CMTime, tolerance: CMTime) -> CNDecision?`](/documentation/Cinematic/CNScript-1ispe/decision(at:tolerance:))

The closest decision to the given time within the given tolerance.

[`func decision(before: CMTime) -> CNDecision?`](/documentation/Cinematic/CNScript-1ispe/decision(before:))

The decision that occurs before the given time.

[`func decisions(in: CMTimeRange) -> [CNDecision]`](/documentation/Cinematic/CNScript-1ispe/decisions(in:))

All decisions within the given time range.

[`func detectionTrack(for: CNDecision) -> CNDetectionTrack?`](/documentation/Cinematic/CNScript-1ispe/detectionTrack(for:)-1xvsa)

A detection track representing all detections selected by a given decision.

[`func detectionTrack(for: CNDetectionID) -> CNDetectionTrack?`](/documentation/Cinematic/CNScript-1ispe/detectionTrack(for:)-6f8mk)

A detection track representing all detections with the given detection ID, over the entire Cinematic script.

[`func frame(at: CMTime, tolerance: CMTime) -> CNScript.Frame?`](/documentation/Cinematic/CNScript-1ispe/frame(at:tolerance:))

The closest frame to the given time within the given tolerance.

[`func frames(in: CMTimeRange) -> [CNScript.Frame]`](/documentation/Cinematic/CNScript-1ispe/frames(in:))

All frames within the given time range.

[`func primaryDecision(at: CMTime) -> CNDecision?`](/documentation/Cinematic/CNScript-1ispe/primaryDecision(at:))

The primary decision that’s in effect at the specified time, unless it’s outside the time range of the Cinematic script.

[`func reload(changes: CNScript.Changes?)`](/documentation/Cinematic/CNScript-1ispe/reload(changes:))

Reloads the Cinematic script with optional changes applied, removing any previous changes made.

[`func removeAllUserDecisions()`](/documentation/Cinematic/CNScript-1ispe/removeAllUserDecisions())

Removes all user decisions and reverts to base decisions only.

[`func removeDetectionTrack(CNDetectionTrack) -> Bool`](/documentation/Cinematic/CNScript-1ispe/removeDetectionTrack(_:))

Removes the user-created detection track.

[`func removeUserDecision(CNDecision) -> Bool`](/documentation/Cinematic/CNScript-1ispe/removeUserDecision(_:))

Removes an existing user decision.

[`func secondaryDecision(at: CMTime) -> CNDecision?`](/documentation/Cinematic/CNScript-1ispe/secondaryDecision(at:))

If a given time is during a focus transition, the system transitions toward a secondary decision.

[`func timeRangeOfTransition(after: CNDecision) -> CMTimeRange`](/documentation/Cinematic/CNScript-1ispe/timeRangeOfTransition(after:))

The time range during which the focus transitioned away from the given decision.

[`func timeRangeOfTransition(before: CNDecision) -> CMTimeRange`](/documentation/Cinematic/CNScript-1ispe/timeRangeOfTransition(before:))

The time range during which the focus transitioned toward the given decision.

[`func userDecisions(in: CMTimeRange) -> [CNDecision]`](/documentation/Cinematic/CNScript-1ispe/userDecisions(in:))

All user decisions in the given time range.

## Relationships

### Conforms To

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Sendable`](/documentation/Swift/Sendable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)