# IVS iOS 廣播 SDK 的進階使用案例 \$1 低延遲串流 以下介紹一些進階使用案例，銜接上述基本設定繼續延伸。 ## 建立廣播組態 在這裡，我們建立有兩個混音器插槽的自訂組態，可讓我們將兩個影片來源綁定到混音器。一個 (`custom`) 是全螢幕，並配置於另一個 (`camera`) 後方，前方的插槽較小，位於右下角。請注意，對於 `custom` 插槽，我們並不設定位置、大小或長寬比模式。因為我們未設定這些參數，插槽將使用影片設定的大小和位置。 ``` let config = IVSBroadcastConfiguration() try config.audio.setBitrate(128_000) try config.video.setMaxBitrate(3_500_000) try config.video.setMinBitrate(500_000) try config.video.setInitialBitrate(1_500_000) try config.video.setSize(CGSize(width: 1280, height: 720)) config.video.defaultAspectMode = .fit config.mixer.slots = [ try { let slot = IVSMixerSlotConfiguration() // Do not automatically bind to a source slot.preferredAudioInput = .unknown // Bind to user image if unbound slot.preferredVideoInput = .userImage try slot.setName("custom") return slot }(), try { let slot = IVSMixerSlotConfiguration() slot.zIndex = 1 slot.aspect = .fill slot.size = CGSize(width: 300, height: 300) slot.position = CGPoint(x: config.video.size.width - 400, y: config.video.size.height - 400) try slot.setName("camera") return slot }() ] ``` ## 建立廣播工作階段 (進階版) 按照您在[基本範例](broadcast-ios-getting-started.md#broadcast-ios-create-session)中的作法建立 `IVSBroadcastSession`，但在此提供自訂組態。同時為裝置陣列提供 `nil`，因為我們將手動新增。 ``` let broadcastSession = try IVSBroadcastSession( configuration: config, // The configuration we created above descriptors: nil, // We’ll manually attach devices after delegate: self) ``` ## 逐一查看和連接攝影機裝置 在這裡，我們逐一查看開發套件偵測到的輸入裝置。開發套件只會傳回 iOS 上的內建裝置。即使藍牙音訊裝置已連線，它們也會顯示為內建裝置。如需詳細資訊，請參閱[IVS iOS 廣播 SDK 中的已知問題和解決方法 \$1 低延遲串流](broadcast-ios-issues.md)。 一旦我們找到要使用的裝置，就呼叫 `attachDevice` 予以連接： ``` let frontCamera = IVSBroadcastSession.listAvailableDevices() .filter { $0.type == .camera && $0.position == .front } .first if let camera = frontCamera { broadcastSession.attach(camera, toSlotWithName: "camera") { device, error in // check error } } ``` ## 交換攝影機 ``` // This assumes you’ve kept a reference called `currentCamera` that points to the current camera. let wants: IVSDevicePosition = (currentCamera.descriptor().position == .front) ? .back : .front // Remove the current preview view since the device will be changing. previewView.subviews.forEach { $0.removeFromSuperview() } let foundCamera = IVSBroadcastSession .listAvailableDevices() .first { $0.type == .camera && $0.position == wants } guard let newCamera = foundCamera else { return } broadcastSession.exchangeOldDevice(currentCamera, withNewDevice: newCamera) { newDevice, _ in currentCamera = newDevice if let camera = newDevice as? IVSImageDevice { do { previewView.addSubview(try finalCamera.previewView()) } catch { print("Error creating preview view \(error)") } } } ``` ## 建立自訂輸入來源 若要輸入應用程式產生的聲音或影像資料，請使用 `createImageSource` 或 `createAudioSource`。這兩種方法都會建立像其他任何裝置一樣可以繫結至混音器的虛擬裝置 (`IVSCustomImageSource` 和 `IVSCustomAudioSource`)。 這兩種方法所傳回的裝置都會透過 `onSampleBuffer` 函數接受 `CMSampleBuffer`： + 對於影片來源，像素格式必須是 `kCVPixelFormatType_32BGRA`、`420YpCbCr8BiPlanarFullRange` 或 `420YpCbCr8BiPlanarVideoRange`。 + 對於音訊來源，緩衝區必須包含線性 PCM 資料。 您無法使用 `AVCaptureSession` 搭配攝影機輸入以提供自訂影像來源，同時也使用廣播開發套件提供的攝影機裝置。如果您想同時使用多部攝影機，請使用 `AVCaptureMultiCamSession` 並提供兩個自訂影像來源。 自訂影像來源主要應與靜態內容 (例如影像) 或影片內容搭配使用： ``` let customImageSource = broadcastSession.createImageSource(withName: "video") try broadcastSession.attach(customImageSource, toSlotWithName: "custom") ``` ## 監控網路連線 行動裝置通常會在外出時暫時中斷網路連線，隨後重新連上網路。因此，重要的是監控您應用程式的網路連線，並於情況變更時適當地回應。 當廣播者的連線中斷時，廣播開發套件的狀態會依序變更為 `error` 和 `disconnected`。您將透過 `IVSBroadcastSessionDelegate` 收到這些變更的通知。當您收到這些狀態變更時： 1. 監控廣播應用程式的連線狀態，並於連線恢復時以您的端點和串流金鑰呼叫 `start`。 1. **重要：**監控狀態委派回呼，並確保再次呼叫 `start` 後狀態變更為 `connected`。 ## 分離裝置 如果您要分離 (而不是取代) 裝置，請使用 `IVSDevice` 或 `IVSDeviceDescriptor`： ``` broadcastSession.detachDevice(currentCamera) ``` ## ReplayKit 整合 若要在 iOS 上串流裝置的螢幕和系統音訊，您必須與 [ReplayKit](https://developer.apple.com/documentation/replaykit?language=objc) 整合。Amazon IVS 廣播開發套件可讓您輕鬆使用 `IVSReplayKitBroadcastSession` 與 ReplayKit 整合。在您的 `RPBroadcastSampleHandler` 子類別中，建立 `IVSReplayKitBroadcastSession` 的執行個體，然後： + 在 `broadcastStarted` 中啟動工作階段 + 在 `broadcastFinished` 中停止工作階段 工作階段物件會有螢幕影像、應用程式音訊和麥克風音訊的三個自訂來源。將 `processSampleBuffer` 中提供的 `CMSampleBuffers` 傳遞給這些自訂來源。 若要處理裝置方向，您必須從範例緩衝區擷取 ReplayKit 專屬中繼資料。使用下列程式碼： ``` let imageSource = session.systemImageSource; if let orientationAttachment = CMGetAttachment(sampleBuffer, key: RPVideoSampleOrientationKey as CFString, attachmentModeOut: nil) as? NSNumber, let orientation = CGImagePropertyOrientation(rawValue: orientationAttachment.uint32Value) { switch orientation { case .up, .upMirrored: imageSource.setHandsetRotation(0) case .down, .downMirrored: imageSource.setHandsetRotation(Float.pi) case .right, .rightMirrored: imageSource.setHandsetRotation(-(Float.pi / 2)) case .left, .leftMirrored: imageSource.setHandsetRotation((Float.pi / 2)) } } ``` 您可以使用 `IVSBroadcastSession` 取代 `IVSReplayKitBroadcastSession` 來整合 ReplayKit。不過，ReplayKit 專屬變數有多項為了減少內部記憶體使用量所做的修改，以保持不超過 Apple 的廣播延伸記憶體限制。 ## 取得建議的廣播設定 若要在開始廣播之前評估使用者的連線，請使用 `IVSBroadcastSession.recommendedVideoSettings` 來執行簡短的測試。在測試執行時，您會收到數個建議，依建議強烈程度 (從高到低) 排序。在此版本的開發套件中，您無法重新設定目前的 `IVSBroadcastSession`，所以需要將其重新配置，然後使用建議的設定重新建立。您將持續收到 `IVSBroadcastSessionTestResults`，直到 `result.status` 為 `Success` 或 `Error` 為止。您可以使用 `result.progress` 檢查進度。 Amazon IVS 支援的最大位元速率為 8.5 Mbps (適用於 `type` 為 `STANDARD` 或 `ADVANCED` 的頻道)，所以此方法傳回的 `maximumBitrate` 絕不會超過 8.5 Mbps。由於網路效能可能有微小波動，此方法傳回之建議的 `initialBitrate` 會稍微小於測試中測得的真實位元速率。(通常不建議使用 100% 的可用頻寬)。 ``` func runBroadcastTest() { self.test = session.recommendedVideoSettings(with: IVS_RTMPS_URL, streamKey: IVS_STREAMKEY) { [weak self] result in if result.status == .success { self?.recommendation = result.recommendations[0]; } } } ``` ## 使用自動重新連線 如果廣播在未呼叫 `stop` API 的情況下意外停止，IVS 會支援自動重新連線至廣播 (例如，網路連線暫時中斷)。若要啟用自動重新連線，請將 `IVSBroadcastConfiguration.autoReconnect` 上的 `enabled` 屬性設定為 `true`。 當某些情況導致串流意外停止時，SDK 會按照線性退避策略重試最多 5 次。SDK 會透過 `IVSBroadcastSessionDelegate.didChangeRetryState` 函數通知您的應用程式重試狀態的相關資訊。 自動重新連線會在背景透過將優先順序號碼 (從 1 開始) 附加至所提供之串流金鑰的結尾，以使用 IVS [串流接收](streaming-config.md#streaming-config-stream-takeover)功能。在 `IVSBroadcastSession` 執行個體的持續時間內，每次嘗試重新連線時，該數字會遞增 1。這表示如果裝置在廣播期間中斷連線 4 次，且每次中斷皆需要重試 1 到 4 次，則上次串流上傳的優先順序可能介於 5 到 17 之間。因此，*我們建議您不要在 SDK 中針對相同頻道啟用自動重新連線時，使用其他裝置的 IVS 串流接管*。我們無法保證 SDK 目前使用的優先順序，如果其他裝置接管，SDK 將會嘗試以更高的優先順序重新連線。 ## 使用背景影片 您可以繼續進行非 RelayKit 廣播，即使您的應用程式在背景中也是如此。 為了節省電力並保持前景應用程式有回應，iOS 一次只允許一個應用程式存取 GPU。Amazon IVS 廣播 SDK 在影片管道的多個階段使用 GPU，包括合成多個輸入來源、擴展影像以及編碼影像。雖然廣播應用程式位於背景，但無法保證開發套件可以執行上述任何動作。 若要解決此問題，請使用 `createAppBackgroundImageSource` 方法。它可讓開發套件在背景中繼續廣播影片和音訊。它會傳回 `IVSBackgroundImageSource`，這是一個正常的 `IVSCustomImageSource`，其中包含其他 `finish` 函數。提供給背景影像來源的每個 `CMSampleBuffer` 都會以原始 `IVSVideoConfiguration` 提供的影格速率編碼。`CMSampleBuffer` 上的時間戳記會遭到忽略。 接著，開發套件會擴展和編碼這些影像並快取它們，以便在您的應用程式進入背景時自動循環該摘要。當您的應用程式回到前景時，附加的影像裝置會再次變成作用中，而且預先編碼的串流會停止循環。 若要復原此程序，請使用 `removeImageSourceOnAppBackgrounded`。只有在您想要明確地還原開發套件的背景行為時，才需要呼叫此方法，否則，它會在取消配置 `IVSBroadcastSession` 時自動清除。 **備註：***強烈建議您在設定廣播工作階段時呼叫此方法，工作階段才能上線。*此方法的成本高昂 (它會將影片編碼)，因此在此方法執行時直播的效能可能會降低。 ### 範例：為背景影片產生靜態影像 將單一影像提供給背景來源會產生該靜態影像的完整 GOP。 以下為使用 CIImage 的範例： ``` // Create the background image source guard let source = session.createAppBackgroundImageSource(withAttemptTrim: true, onComplete: { error in print("Background Video Generation Done - Error: \(error.debugDescription)") }) else { return } // Create a CIImage of the color red. let ciImage = CIImage(color: .red) // Convert the CIImage to a CVPixelBuffer let attrs = [ kCVPixelBufferCGImageCompatibilityKey: kCFBooleanTrue, kCVPixelBufferCGBitmapContextCompatibilityKey: kCFBooleanTrue, kCVPixelBufferMetalCompatibilityKey: kCFBooleanTrue, ] as CFDictionary var pixelBuffer: CVPixelBuffer! CVPixelBufferCreate(kCFAllocatorDefault, videoConfig.width, videoConfig.height, kCVPixelFormatType_420YpCbCr8BiPlanarFullRange, attrs, &pixelBuffer) let context = CIContext() context.render(ciImage, to: pixelBuffer) // Submit to CVPixelBuffer and finish the source source.add(pixelBuffer) source.finish() ``` 或者，您可以使用綁定的影像，而不是建立純色的 CIImage。這裡顯示的唯一程式碼是如何將 UIImage 轉換為 CIImage 以便搭配上一個範例使用： ``` // Load the pre-bundled image and get it’s CGImage guard let cgImage = UIImage(named: "image")?.cgImage else { return } // Create a CIImage from the CGImage let ciImage = CIImage(cgImage: cgImage) ``` ### 範例：具有 AVAssetImageGenerator 的影片 您可以使用 `AVAssetImageGenerator` 從 `AVAsset` (儘管不是 HLS 串流 `AVAsset`) 產生 `CMSampleBuffers`： ``` // Create the background image source guard let source = session.createAppBackgroundImageSource(withAttemptTrim: true, onComplete: { error in print("Background Video Generation Done - Error: \(error.debugDescription)") }) else { return } // Find the URL for the pre-bundled MP4 file guard let url = Bundle.main.url(forResource: "sample-clip", withExtension: "mp4") else { return } // Create an image generator from an asset created from the URL. let generator = AVAssetImageGenerator(asset: AVAsset(url: url)) // It is important to specify a very small time tolerance. generator.requestedTimeToleranceAfter = .zero generator.requestedTimeToleranceBefore = .zero // At 30 fps, this will generate 4 seconds worth of samples. let times: [NSValue] = (0...120).map { NSValue(time: CMTime(value: $0, timescale: CMTimeScale(config.video.targetFramerate))) } var completed = 0 let context = CIContext(options: [.workingColorSpace: NSNull()]) // Create a pixel buffer pool to efficiently feed the source let attrs = [ kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_420YpCbCr8BiPlanarFullRange, kCVPixelBufferCGImageCompatibilityKey: kCFBooleanTrue, kCVPixelBufferCGBitmapContextCompatibilityKey: kCFBooleanTrue, kCVPixelBufferMetalCompatibilityKey: kCFBooleanTrue, kCVPixelBufferWidthKey: videoConfig.width, kCVPixelBufferHeightKey: videoConfig.height, ] as CFDictionary var pool: CVPixelBufferPool! CVPixelBufferPoolCreate(kCFAllocatorDefault, nil, attrs, &pool) generator.generateCGImagesAsynchronously(forTimes: times) { requestTime, image, actualTime, result, error in if let image = image { // convert to CIImage then CVpixelBuffer let ciImage = CIImage(cgImage: image) var pixelBuffer: CVPixelBuffer! CVPixelBufferPoolCreatePixelBuffer(kCFAllocatorDefault, pool, &pixelBuffer) context.render(ciImage, to: pixelBuffer) source.add(pixelBuffer) } completed += 1 if completed == times.count { // Mark the source finished when all images have been processed source.finish() } } ``` 使用 `AVPlayer` 和 `AVPlayerItemVideoOutput` 可以產生 `CVPixelBuffers`。但是，這需要使用 `CADisplayLink` 並且更接近即時執行，同時 `AVAssetImageGenerator` 可以更快地處理影格。 ### 限制 您的應用程式需要[背景音訊授權](https://developer.apple.com/documentation/xcode/configuring-background-execution-modes)，以避免在進入背景後暫停。 `createAppBackgroundImageSource`只有在應用程式在前景時才能呼叫 ，因為它需要存取 GPU 才能完成。 `createAppBackgroundImageSource` 一律編碼為完整的 GOP。例如，如果您的關鍵影格間隔為 2 秒 (預設)，且以 30 fps 執行，則會編碼 60 個影格的倍數。 + 如果提供的影格少於 60 個，則無論裁剪選項的值為何，都會重複最後一個影格，直到達到 60 個影格為止。 + 如果提供的影格超過 60 個，且裁剪選項為 `true`，則會捨棄最後 N 個影格，其中 N 是提交的影格總數除以 60 的餘數。 + 如果提供的影格超過 60 個，且裁剪選項為 `false`，則會重複最後一個影格，直到達到 60 個影格的下一個倍數為止。