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,14 @@ import Foundation
 public typealias UploadResult = Result<MuxUpload.Success, MuxUpload.UploadError>
 
 /**
- Uploads a video file to a previously-created Direct Upload. Create instances of this object using ``Builder``
+ Uploads a media asset to Mux using a previously-created
+ Direct Upload signed URL.
+
+ Before initializing ``MuxUpload``, create a
+ [direct upload](https://docs.mux.com/api-reference#video/tag/direct-uploads)
+ using the Mux API first. The signed URL you'll get back
+ after creating a direct upload is needed to get the
+ ``MuxUpload`` ready to deliver your media asset to Mux.
 
  TODO: usage here
  */
@@ -34,7 +41,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
@@ -59,6 +66,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):
@@ -151,9 +160,12 @@ public final class MuxUpload: Hashable, Equatable {
 
     }
 
-    /// Initializes a MuxUpload
+    /// Initializes a MuxUpload from a local file URL
+    ///
     /// - 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,
@@ -162,7 +174,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,
@@ -171,40 +184,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

@@ -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 {