Adjustments

Initializer API adjustments

Place extension methods into dedicated directories

Polish inline API documentation

Author: andrewjl-mux

Sources/MuxUploadSDK/PublicAPI/AVFoundation+MuxUpload/MuxUpload+AVFoundation.swift

@@ -0,0 +1,33 @@
+//
+//  MuxUpload+AVFoundation.swift
+//
+
+import AVFoundation
+import Foundation
+
+extension MuxUpload {
+
+    /// Initializes a MuxUpload from an ``AVAsset``
+    ///
+    /// - Parameters:
+    ///    - uploadURL: the URL of the direct upload that's
+    ///    included in the create a new direct upload URL
+    ///    [response](https://docs.mux.com/api-reference#video/operation/create-direct-upload)
+    ///     - inputAsset: the asset containing audiovisual
+    ///     media to be used as the input for the direct
+    ///     upload
+    ///     - options: options used to control the direct
+    ///    upload of the input to Mux
+    public convenience init(
+        uploadURL: URL,
+        inputAsset: AVAsset,
+        options: UploadOptions
+    ) {
+        self.init(
+            input: UploadInput(asset: inputAsset),
+            options: options,
+            uploadManager: .shared
+        )
+    }
+
+}

Sources/MuxUploadSDK/PublicAPI/MuxUpload+AVFoundation.swift

@@ -11,7 +11,8 @@ import Foundation
 public typealias UploadResult = Result<MuxUpload.Success, MuxUpload.UploadError>
 
 ///
-/// Uploads a video file to a previously-created Mux Video Direct Upload.
+/// Uploads a media asset to Mux using a previously-created
+/// Direct Upload signed URL.
 ///
 /// This class is part of a full-stack workflow for uploading video files to Mux Video. In order to use this object you must first have
 /// created a [Direct Upload](https://docs.mux.com/guides/video/upload-files-directly) on your server backend.
@@ -66,7 +67,7 @@ public final class MuxUpload : Hashable, Equatable {
         input.uploadInfo
     }
 
-    /// Indicates the status of the upload as it goes
+    /// Indicates the status of the upload input as it goes
     /// through its lifecycle
     public enum InputStatus {
         /// Upload initialized and not yet started
@@ -91,6 +92,8 @@ public final class MuxUpload : Hashable, Equatable {
         case uploadFailed(AVAsset, Status, UploadResult)
     }
 
+    /// Current status of the upload input as it goes through
+    /// its lifecycle
     public var inputStatus: InputStatus {
         switch input.status {
         case .ready(let sourceAsset):
@@ -183,9 +186,12 @@ public final class MuxUpload : Hashable, Equatable {
 
     }
 
-    /// Initializes a MuxUpload with the given configuration
+    /// Initializes a MuxUpload from a local file URL with
+    /// the given configuration
     /// - Parameters:
-    ///     - uploadURL: the URL of the direct upload
+    ///    - uploadURL: the URL of the direct upload that's
+    ///    included in the create a new direct upload URL
+    ///    [response](https://docs.mux.com/api-reference#video/operation/create-direct-upload)
     ///     - videoFileURL: the file:// URL of the upload
     ///     input
     ///     - chunkSize: the size of chunks when uploading,
@@ -194,7 +200,8 @@ public final class MuxUpload : Hashable, Equatable {
     ///     a failed chunk upload request
     ///     - inputStandardization: enable or disable input
     ///     standardization by the SDK locally
-    ///     - optOutOfEventTracking: opt out of event tracking
+    ///     - eventTracking: options to opt out of event
+    ///     tracking
     public convenience init(
         uploadURL: URL,
         videoFileURL: URL,
@@ -203,40 +210,43 @@ public final class MuxUpload : Hashable, Equatable {
         inputStandardization: UploadOptions.InputStandardization = .init(
             targetResolution: UploadOptions.InputStandardization.ResolutionPreset.default
         ),
-        optOutOfEventTracking: Bool = false
+        eventTracking: UploadOptions.EventTracking = UploadOptions.EventTracking(optedOut: false)
     ) {
-        let uploadSettings = UploadOptions(
-            inputStandardization: inputStandardization,
-            transport: UploadOptions.Transport(
-                chunkSize: chunkSize,
-                retriesPerChunk: retriesPerChunk
-            ),
-            eventTracking: UploadOptions.EventTracking(
-                optedOut: optOutOfEventTracking
-            )
-        )
-
-        let inputSourceAsset = AVAsset(url: videoFileURL)
-
-        let input = UploadInput(status: .ready(inputSourceAsset))
-
         self.init(
-            input: input,
-            options: uploadSettings,
+            input: UploadInput(asset: AVAsset(url: videoFileURL)),
+            options: UploadOptions(
+                inputStandardization: inputStandardization,
+                transport: UploadOptions.Transport(
+                    chunkSize: chunkSize,
+                    retriesPerChunk: retriesPerChunk
+                ),
+                eventTracking: eventTracking
+            ),
             uploadManager: .shared
         )
     }
 
+    /// Initializes a MuxUpload from a local file URL
+    ///
+    /// - Parameters:
+    ///    - uploadURL: the URL of the direct upload that's
+    ///    included in the create a new direct upload URL
+    ///    [response](https://docs.mux.com/api-reference#video/operation/create-direct-upload)
+    ///     - inputFileURL: the file:// URL of the upload
+    ///     input
+    ///     - options: options used to control the direct
+    ///    upload of the input to Mux
     public convenience init(
         uploadURL: URL,
         inputFileURL: URL,
         options: UploadOptions
     ) {
-        let inputSourceAsset = AVAsset(url: inputFileURL)
-        let input = UploadInput(status: .ready(inputSourceAsset))
-
         self.init(
-            input: input,
+            input: UploadInput(
+                asset: AVAsset(
+                    url: inputFileURL
+                )
+            ),
             manage: true,
             options: options,
             uploadManager: .shared

Sources/MuxUploadSDK/PublicAPI/MuxUpload.swift

@@ -92,6 +92,8 @@ public struct UploadOptions {
             targetResolution: .default
         )
 
+        // Kept private to an invalid combination of parameters
+        // being used for initialization
         private init(
             isEnabled: Bool,
             targetResolution: ResolutionPreset
@@ -100,7 +102,13 @@ public struct UploadOptions {
             self.targetResolution = targetResolution
         }
 
+        /// Used to initialize ``UploadOptions.InputStandardization``
+        /// with a target resolution
         ///
+        /// - Parameters:
+        ///     - targetResolution: if the input resolution
+        ///     exceeds 1080p, it will be set to the preset
+        ///     after undergoing standardization
         public init(
             targetResolution: ResolutionPreset
         ) {

Sources/MuxUploadSDK/PublicAPI/Options/UploadOptions.swift

@@ -7,27 +7,32 @@ import Photos
 
 extension PHAsset {
 
-    /// Asynchronously initializes ``MuxUpload`` from a
-    /// requesting for an ``AVAsset`` containing the input.
-    /// A ``MuxUpload`` can only be initialized from a ``PHAsset``
-    /// whose ``PHAsset.mediaType`` is
-    /// ``PHAssetMediaType.video``.
+    /// Convenience method that requests an ``AVAsset``
+    /// containing audiovisual media associated with the callee
+    /// ``PHAsset``. If the request succeeds ``MuxUpload``
+    /// is initialized with the received ``AVAsset``
     ///
+    /// A ``MuxUpload`` can only be initialized from a ``PHAsset``
+    /// whose ``PHAsset.mediaType`` is ``PHAssetMediaType.video``
     ///
     /// - Parameters:
-    ///    - imageManager: Photos image manager
+    ///    - imageManager: an object that facilitates retrieval
+    ///    of asset data associated with the callee
     ///    - requestOptions: options used when requesting
-    ///    an ``AVAsset`` from the `imageManager`
-    ///    - uploadURL: the direct upload URL
-    ///    - options: the upload settings
-    ///    - completion: receives the initialized MuxUpload
-    ///    when it is ready, receives nil if initialization
-    ///    failed or if the ``PHAsset`` is not a video.
+    ///    an ``AVAsset`` from a ``PHImageManager`
+    ///    - options: options used to control the direct
+    ///    upload of the input to Mux
+    ///    - uploadURL: the URL of the direct upload that's
+    ///    included in the create a new direct upload URL
+    ///    [response](https://docs.mux.com/api-reference#video/operation/create-direct-upload)
+    ///    - completion: called when initialized ``MuxUpload``
+    ///    is ready, receives nil if the asset data request
+    ///    failed or if the ``PHAsset`` callee is not a video
     func prepareForDirectUpload(
         from imageManager: PHImageManager = .default(),
         requestOptions: PHVideoRequestOptions,
-        uploadURL: URL,
         options: UploadOptions,
+        uploadURL: URL,
         completion: @escaping (MuxUpload?) -> ()
     ) {
         if mediaType != .video {