Sessions

  • 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 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.

    See more

    Declaration

    Swift

    @objcMembers
    public class Session : NSObject, Codable
  • For more information see Session documentation.

    See more

    Declaration

    Swift

    @objcMembers
    public class SessionImage : NSObject, Codable
  • For more information see Session documentation.

    See more

    Declaration

    Swift

    @objcMembers
    public class SessionVideo : NSObject, Codable
  • For more information see Session documentation.

    See more

    Declaration

    Swift

    @objcMembers
    public class SessionVideoSegment : NSObject, Codable