Session

@objcMembers
public class Session : NSObject, Codable

Overview

A Session is analogous to a project in photo and video editing software. A session can contain either a SessionImage or SessionVideo composed of one or more SessionVideoSegment objects. Sessions are mutable and store all information related to the rendering of their media including files, crop rects, filters, trim times, etc. They also contain metadata like modification time, userInfo, and latitude/longitude.

You can use session objects in several different ways:

  • Assign a session to a PreviewController object to display the session in your interface.

  • Initialize an EditController with a session so you can make edits visually.

  • Programmatically make real-time modifications to a session like set filters, crop rects, segment trim times, etc.

Creating Session Objects

When creating session objects using the methods of this class, you must have an existing image or video located in a file, UIImage, or local AVAsset. You cannot create an empty session and later add media. There are a couple options for creating session objects, each of which is best for specific situations:

  • init(image:) creates a session with the provided UIImage.

  • init(asset:sessionReady:) creates a session with the provided AVAsset.

  • init(assets:sessionReady:) creates a session with the provided AVAssets where each asset corresponds to a segment in the session video.

  • init(assets:renderSize:sessionReady:) creates a session of a specific pixel dimension and with the provided AVAssets where each asset corresponds to a segment in the session video.

After a session is successfully created you may delete any local image/video files that you used to create the session.

Saving/Restoring Sessions

By default, all sessions are automatically saved to file and accessible from the users Drafts in the LibraryController and the savedSessions array. If you do not want a session to persist in memory and on disk, you should call destroy() when the session is no longer needed. No further action is required on your part.

If you want to know how to retrieve a saved session on startup see SessionManager for more information.

Modifying Sessions

Sessions can also be edited programmatically instead of visually.

For example, setting the primaryFilter of an image to Wilshire:

session.image!.primaryFilter = SessionFilterWilshire()

Applying a Brightness filter to an image:

let brightnessFilter = SessionFilterBrightness()
brightnessFilter.normalizedIntensity = 0.2
session.image!.filters = [brightnessFilter]

Applying a Saturation filter to a whole video:

let saturationFilter = SessionFilterSaturation()
saturationFilter.normalizedIntensity = 0.3
session.video!.filters = [saturationFilter]

Applying a Contrast filter to the first segment of a video:

let segment = session.video!.videoSegments.first!
let contrastFilter = SessionFilterContrast()
contrastFilter.normalizedIntensity = 0.2
segment.filters = [contrastFilter]

Trimming a segment so it starts at one second in, with a duration of two seconds:

let segment = session.video!.videoSegments.first!
segment.trimStartTime = CMTime(seconds: 1, preferredTimescale: segment.duration.timescale)
segment.trimDuration = CMTime(seconds: 2, preferredTimescale: segment.duration.timescale)

Rotating the first segment of a video with preferredTransform:

let segment = session.video!.videoSegments.first!
segment.preferredTransform = .rotated180Degrees(segment.naturalSize)
segment.cropRect = segment.suggestedCropRect()

Increasing the speed of the first segment of a video:

let segment = session.video!.videoSegments.first!
segment.speedMultiplier = 2 // 2x faster

You can present the EditController after making programmatic edits and it will reflect your changes. Additionally, the PreviewController will reflect all programmatic edits in real-time.

After making programmatic edits to a session, you should manually call session.save().

Warning

If you make programmatic changes to a session that is currently displayed by an EditController it may result in undocumented behavior.

Exporting Session Media

See the VideoExporter and ImageExporter classes.

If you need to retrieve thumbnails for media, you can do so with the SessionImage and SessionVideoSegment requestThumbnail() functions respectively.

Creating a Session

  • Creates a Session with the provided image.

    Declaration

    Swift

    public convenience init(image: UIImage)

    Parameters

    image

    The image to create the session with.

  • Creates a Session with the provided local asset. The asset will correspond with a single segment in the session video.

    The sessionReady closure will be called when the session is ready and can be used. After sessionReady is called, you may delete or move the file you used to create your asset.

    Declaration

    Swift

    public convenience init(asset: AVAsset, sessionReady: @escaping (Session?, SessionInitError?) -> ())

    Parameters

    asset

    The local asset to create the session with. Asset isExportable variable must be true.
    sessionReady

    Called when the session is ready and can be used. If the session was created successfully, a session will be present. If the session was not created successfully, an error will be present.

  • Creates a Session with the provided local assets. Each asset you provide will correspond with a segment in the session video. The suggestedCropRect() will be used for the crop rect of each segment.

    The sessionReady closure will be called when the session is ready and can be used. After sessionReady is called, you may delete or move the files you used to create your assets.

    Precondition

    You must provide at least one asset.

    Declaration

    Swift

    public convenience init(assets: [AVAsset], sessionReady: @escaping (Session?, SessionInitError?) -> ())

    Parameters

    assets

    The local assets to create the session with. Each asset isExportable variable must be true.
    sessionReady

    Called when the session is ready and can be used. If the session was created successfully, a session will be present. If the session was not created successfully, an error will be present.

  • Creates a Session with the provided local assets. Each asset you provide will correspond with a segment in the session video. The suggestedCropRect() will be used for the crop rect of each segment.

    The sessionReady closure will be called when the session is ready and can be used. After sessionReady is called, you may delete or move the files you used to create your assets.

    Precondition

    You must provide at least one asset.

    Declaration

    Swift

    public convenience init(assets: [AVAsset], renderSize: CGSize? = nil, sessionReady: @escaping (Session?, SessionInitError?) -> ())

    Parameters

    assets

    The local assets to create the session with. Each asset isExportable variable must be true.
    renderSize

    The pixel dimensions of the final video. If you do not include a renderSize the video will automatically inherit its renderSize from the actualSize of the first segment.
    sessionReady

    Called when the session is ready and can be used. If the session was created successfully, a session will be present. If the session was not created successfully, an error will be present.

Encoding/Decoding a Session

  • Creates a Session with the provided decoder. You do not need to worry about calling this since sessions are automatically saved and restored. Saved sessions can be found in the Drafts on the LibraryController or the savedSessions array.

    Declaration

    Swift

    public required init(from decoder: Decoder) throws

    Parameters

    decoder

    The decoder.

  • Encodes a Session with the provided encoder. You do not need to worry about calling this since sessions are automatically saved and restored. Saved sessions can be found in the Drafts on the LibraryController or the savedSessions array.

    If you wish to ship analytics information to a server about what modifications were made to an image or video, you can use a JSONEncoder to save the session to a string or file. The contents of these files may change in future SDK releases.

    Declaration

    Swift

    public func encode(to encoder: Encoder) throws

    Parameters

    encoder

    The encoder.

Associated Media

  • An image associated with the session, if any.

    A session will have either a video or image associated with it, but never both.

    Declaration

    Swift

    public private(set) var image: SessionImage? { get }

  • A video associated with the session, if any.

    A session will have either a video or image associated with it, but never both.

    Declaration

    Swift

    public private(set) var video: SessionVideo? { get }

  • Indicates the type of media associated with a session.

    Declaration

    Swift

    public var mediaType: MediaType { get }

Metadata

  • A unique ID assigned to this session.

    Declaration

    Swift

    public private(set) var sessionID: Int { get }

  • UTC Date created, set when the session is first initialized.

    Declaration

    Swift

    public private(set) var dateCreated: Date { get }

  • UTC Date modified, set when the session is saved.

    Declaration

    Swift

    public private(set) var dateModified: Date { get }

  • The source from which the session derived.

    If the session was generated by a decoder then this is set to .drafts.

    Default value: .user

    Declaration

    Swift

    public internal(set) var source: SessionSource { get }

  • Set this to any information you want associated with this session.

    The SDK will handle calling save() after you set this.

    Must be a valid JSON object. https://developer.apple.com/documentation/foundation/jsonserialization/1418461-isvalidjsonobject

    Default value: nil

    Declaration

    Swift

    public var userInfo: [AnyHashable : Any]? { get set }

Session State

  • If the session can be found in the savedSessions array this will be true.

    Declaration

    Swift

    public var isSaved: Bool { get }

  • If the session should never be saved, written to file or the savedSessions array, set this to true. This is helpful if you need a temporary session that can be easily thrown away.

    Anything that is written to file for this session (e.g. video files) will be deleted on next restart if you do not call destroy() before then. If you are creating many temporary sessions, make sure to call destroy() when done with a session to prevent memory or disk space from running out.

    Default value: false

    Declaration

    Swift

    public var isTransient: Bool { get set }

  • Indicates if destroy() has been called on the session.

    Default value: false

    Declaration

    Swift

    public private(set) var destroyed: Bool { get set }

  • Set this to true if you do not want this session to appear in Drafts on the LibraryController.

    Warning

    Improper usage of this may lead to runaway growth of savedSessions array and disk usage since all sessions are automatically saved. You may be unaware that the session still exists since it will not be visible in your Drafts.

    Default value: false

    Declaration

    Swift

    public var hidden: Bool { get set }

Saving/Destroying a Session

  • The SDK automatically saves every Session that interacts with a view controller (EditController, LibraryController, CameraController) so you should not need to call this.

    You should only call this when you have finished making a set of programmatic changes to a session.

    When a session is saved it will be written to file and inserted into the savedSessions array (if not already present). It will also appear in the users Drafts on the LibraryController.

    Every variable in the session will be saved, unless the documentation for a specific variable explicitly states:

    “Does not persist.”

    Precondition

    isTransient and destroyed must be false for a session to successfully save.

    Declaration

    Swift

    public func save()

  • Sessions are automatically saved so you a responsible for calling this when you are done with a session (unless noted otherwise). If you do not destroy a session it will persist in the users Drafts in memory and on disk.

    A documentation example of where a session should not be destroyed is in the containerController(_:willShowEditController:withSession:) delegate call.

    This deletes all files associated with a session (videos, images, etc.), removes it from the savedSessions array and sets the destroyed variable to true.

    After calling this, the session can no longer be used and you should begin releasing all references to it.

    Declaration

    Swift

    public func destroy()