# Guida introduttiva all'SDK di trasmissione IVS per iOS \$1 Streaming a bassa latenza Questo documento illustra i passaggi necessari per iniziare a utilizzare l'SDK di trasmissione per lo streaming a bassa latenza di Amazon IVS per iOS. ## Installare la libreria Si consiglia di integrare l'SDK di trasmissione tramite Swift Package Manager. (in alternativa, esiste la possibilità di aggiungere il framework al proprio progetto manualmente). ### Consigliato: Integrare l'SDK di trasmissione (Swift Package Manager) 1. Scaricare il file Package.swift da [https://broadcast.live-video.net/1.41.0/Package.swift](https://broadcast.live-video.net/1.41.0/Package.swift). 1. Nel tuo progetto, crea una nuova directory denominata AmazonIVSBroadcast e aggiungila al controllo delle versioni. 1. Inserire il file Package.swift file nella nuova directory. 1. In Xcode, vai su **File > Aggiungi dipendenze del pacchetto** e seleziona **Aggiungi locale…** 1. Passare e selezionare la directory AmazonIVSBroadcast creata e selezionare **Aggiungi pacchetto**. 1. Quando viene richiesto di **scegliere i prodotti del pacchetto per AmazonIVSBroadcast**, selezionare **AmazonIVSBroadcast** come **prodotto del pacchetto** impostando la destinazione dell'applicazione nella sezione **Aggiungi alla destinazione**. 1. Seleziona **Aggiungi pacchetto**. ### Approccio alternativo: installare manualmente il framework 1. Scarica l'ultima versione da [https://'.live-video.net/1.41.0/AmazonIVSBroadcast.xcframework.zip](https://broadcast.live-video.net/1.41.0/AmazonIVSBroadcast.xcframework.zip). 1. Estrarre i contenuti dell'archivio. `AmazonIVSBroadcast.xcframework` contiene l'SDK sia per il dispositivo sia per il simulatore. 1. Incorporare `AmazonIVSBroadcast.xcframework` trascinandolo nella sezione **Framework, librerie e contenuto incorporato** della scheda **Generali** per il target dell'applicazione. ![\[La sezione Framework, librerie e contenuto incorporato della scheda Generali per il target dell'applicazione.\]](http://docs.aws.amazon.com/it_it/ivs/latest/LowLatencyUserGuide/images/iOS_Broadcast_SDK_Guide_xcframework.png) ## Implementare IVSBroadcastSession.Delegate Implementare `IVSBroadcastSession.Delegate`, che consente di ricevere aggiornamenti sullo stato e notifiche relative alle modifiche al dispositivo: ``` extension ViewController : IVSBroadcastSession.Delegate { func broadcastSession(_ session: IVSBroadcastSession, didChange state: IVSBroadcastSession.State) { print("IVSBroadcastSession did change state \(state)") } func broadcastSession(_ session: IVSBroadcastSession, didEmitError error: Error) { print("IVSBroadcastSession did emit error \(error)") } } ``` ## Richiedere autorizzazioni L'app deve richiedere l'autorizzazione per accedere alla fotocamera e al microfono dell'utente. (Questo non riguarda solo Amazon IVS, ma qualsiasi applicazione che abbia bisogno di accedere alle fotocamere e ai microfoni.) Qui, controlliamo se l'utente ha già concesso le autorizzazioni e, in caso contrario, ne facciamo richiesta: ``` switch AVCaptureDevice.authorizationStatus(for: .video) { case .authorized: // permission already granted. case .notDetermined: AVCaptureDevice.requestAccess(for: .video) { granted in // permission granted based on granted bool. } case .denied, .restricted: // permission denied. @unknown default: // permissions unknown. } ``` È necessario eseguire questa operazione per entrambe le tipologie di contenuti multimediali `.video` e `.audio`, se si desidera accedere rispettivamente a fotocamere e microfoni. Inoltre, è necessario aggiungere voci per `NSCameraUsageDescription` e `NSMicrophoneUsageDescription` a `Info.plist`. In caso contrario, quando si tenta di richiedere le autorizzazioni l'app potrebbe subire un arresto anomalo. ## Disabilitare il timer di inattività dell'applicazione Questo passaggio è facoltativo, ma è consigliato. Impedisce al dispositivo di andare in sospensione durante l'utilizzo dell'SDK di trasmissione, che causerebbe l'interruzione della trasmissione. ``` override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) UIApplication.shared.isIdleTimerDisabled = true } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) UIApplication.shared.isIdleTimerDisabled = false } ``` ## (Facoltativo) Impostare AVAudioSession Per impostazione predefinita, l'SDK di trasmissione configurerà l' dell'applicazione `AVAudioSession`. Se si vuole gestirla in modo autonomo, impostare `IVSBroadcastSession.applicationAudioSessionStrategy` su `noAction`. Senza controllo del `AVAudioSession`, l'SDK di trasmissione non è in grado di gestire i microfoni internamente. Per utilizzare i microfoni con l'opzione `noAction`, esiste la possibilità di creare un `IVSCustomAudioSource` e fornire i propri campioni tramite un `AVCaptureSession`, `AVAudioEngine` o un altro strumento che fornisce campioni audio PCM. Se si configura manualmente la `AVAudioSession`, come minimo è necessario impostare la categoria come `.record` o `.playbackAndRecord` e impostarla su `active`. Se si desidera registrare audio da dispositivi Bluetooth, è necessario specificare anche l'opzione `.allowBluetooth`: ``` do { try AVAudioSession.sharedInstance().setCategory(.record, options: .allowBluetooth) try AVAudioSession.sharedInstance().setActive(true) } catch { print("Error configuring AVAudioSession") } ``` Consigliamo di lasciare che l'SDK gestisca questo aspetto. In caso contrario, se si desidera scegliere tra vari dispositivi audio, sarà necessario gestire manualmente le porte. ## Creare la sessione di trasmissione L'interfaccia di trasmissione è `IVSBroadcastSession`. Inizializzare come illustrato di seguito: ``` let broadcastSession = try IVSBroadcastSession( configuration: IVSPresets.configurations().standardLandscape(), descriptors: IVSPresets.devices().frontCamera(), delegate: self) ``` Consultare anche [Creare la sessione di trasmissione (versione avanzata)](broadcast-ios-use-cases.md#broadcast-ios-create-session-advanced) ## Impostare IVSImagePreviewView per l'anteprima Se si desidera visualizzare un'anteprima per un dispositivo fotocamera attivo, aggiungere l'anteprima `IVSImagePreviewView` per il dispositivo dalla gerarchia delle visualizzazioni: ``` // If the session was just created, execute the following // code in the callback of IVSBroadcastSession.awaitDeviceChanges // to ensure all devices have been attached. if let devicePreview = try broadcastSession.listAttachedDevices() .compactMap({ $0 as? IVSImageDevice }) .first? .previewView() { previewView.addSubview(devicePreview) } ``` ## Avviare una trasmissione Al nome host che si riceve nel campo di risposta `ingestEndpoint` dell'operazione `GetChannel` è necessario anteporre `rtmps://` e posporre `/app`. L'URL completo deve essere in questo formato: `rtmps://{{ ingestEndpoint }}/app` ``` try broadcastSession.start(with: IVS_RTMPS_URL, streamKey: IVS_STREAMKEY) ``` L'SDK di trasmissione iOS supporta solo l'acquisizione RTMPS (non l'acquisizione RTMP non sicura). ## Interrompere una trasmissione ``` broadcastSession.stop() ``` ## Gestire gli eventi del ciclo di vita ### Interruzioni dell'audio Ci sono varie situazioni in cui l'SDK di trasmissione non avrà accesso esclusivo all'hardware di ingresso audio. Di seguito si trovano alcuni esempi di situazioni da gestire: + L'utente riceve una telefonata o una chiamata FaceTime + L'utente attiva Siri Con Apple si può rispondere facilmente a questi eventi iscrivendosi a `AVAudioSession.interruptionNotification`: ``` NotificationCenter.default.addObserver( self, selector: #selector(audioSessionInterrupted(_:)), name: AVAudioSession.interruptionNotification, object: nil) ``` Quindi, è possibile gestire l'evento con una delle seguenti opzioni: ``` // This assumes you have a variable `isRunning` which tracks if the broadcast is currently live, and another variable `wasRunningBeforeInterruption` which tracks whether the broadcast was active before this interruption to determine if it should resume after the interruption has ended. @objc private func audioSessionInterrupted(_ notification: Notification) { guard let userInfo = notification.userInfo, let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt, let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return } switch type { case .began: wasRunningBeforeInterruption = isRunning if isRunning { broadcastSession.stop() } case .ended: defer { wasRunningBeforeInterruption = false } guard let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt else { return } let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue) if options.contains(.shouldResume) && wasRunningBeforeInterruption { try broadcastSession.start( with: IVS_RTMPS_URL, streamKey: IVS_STREAMKEY) } @unknown default: break } } ``` ### App mandata in background Su iOS le applicazioni standard non sono autorizzate a utilizzare fotocamere in background. Esistono anche restrizioni sulla codifica video in background: poiché i codificatori hardware sono limitati, solo le applicazioni in primo piano hanno accesso. Per questo motivo, l'SDK di trasmissione termina automaticamente la sua sessione e imposta la sua proprietà `isReady` su `false`. Quando l'applicazione sta per entrare di nuovo in primo piano, l'SDK di trasmissione ricollega tutti i dispositivi alle loro voci `IVSMixerSlotConfiguration` originali. L'SDK di trasmissione lo fa rispondendo a `UIApplication.didEnterBackgroundNotification` e `UIApplication.willEnterForegroundNotification`. Se si forniscono fonti di immagine personalizzate, è necessario prepararsi a gestire queste notifiche. Potrebbe essere necessario prendere ulteriori contromisure per abbatterle prima che il flusso venga terminato. Consultare [Usa video in background](broadcast-ios-use-cases.md#broadcast-ios-background-video) per una soluzione alternativa che consenta lo streaming mentre l'applicazione è in background. ### Media Services (Servizi multimediali) persi In casi molto rari, sui dispositivi iOS si bloccherà l'intero sottosistema multimediale. In questa situazione, non possiamo più trasmettere. Spetterà all'applicazione rispondere in modo appropriato a queste notifiche. Come minimo, consigliamo di iscriversi a queste notifiche: + [mediaServicesWereLostNotification](https://developer.apple.com/documentation/avfaudio/avaudiosession/1616457-mediaserviceswerelostnotificatio) - Rispondere interrompendo la trasmissione e deallocando completamente la propria `IVSBroadcastSession`. Tutti i componenti interni utilizzati dalla sessione di trasmissione verranno invalidati. + [mediaServicesWereResetNotification](https://developer.apple.com/documentation/avfaudio/avaudiosession/1616540-mediaserviceswereresetnotificati) - Rispondere informando gli utenti che possono trasmettere di nuovo. A seconda dei casi d'uso, si potrebbe avere la possibilità di riavviare automaticamente la trasmissione.