MediaPlayer Kit

Description

During an interactive broadcast, you can publish a separate video stream to the remote user through Agora’s SD-RTN™ and adjust the playback of the separate video stream in real time by using MediaPlayer Kit.

Supported formats

• Local video: AVI, MP4, MKV, and FLV file formats.
• Online video: RTMP and RTSP streams.

Usage

Using MediaPlayer Kit, you can start/pause the playback video, adjust the playback progress, adjust the playback volume, and publish the playback video to the remote user:

• If you want to publish the playback video to the remote user, you may need to use a dual process. In a process, you can capture and publish the call video; while in another process, you can publish the playback video stream. If you join the channel with only a process, the remote user can only see the video window corresponding to that process.

• If you do not need to publish the playback video to the remote user, you can use MediaPlayer Kit as your local media player. We will not discuss this scenario here.

Quickly experience MediaPlayer Kit

Prerequisites

• Xcode 10.12 or later.
• Physical macOS 10.12 or later.
• Ensure that your project has a validated provisioning profile certificate.

Use MediaPlayer Kit

1. Download and unzip the MediaPlayerKitQuickstart folder.

2. Open the MediaPlayerKitQuickstart.xcodeproj file with Xcode.

3. Click on the upper left triangle symbol in the Xcode interface to build the project.

4. After a successful compilation, a graphical interface pops up.

   If the compilation fails, check whether a validated provisioning profile certificate is set.

5. Click Settings on the interface to select the video quality seen by the remote user, then click Confirm.

6. Fill in Channel Name, select Join as Broadcaster, then you can see the playback interface of MediaPlayer Kit.
   

7. At the bottom of the interface, you can see the following icons from left to right: Start/Pause the playback video, the progress bar, the volume bar, enables (default)/disables PUBLISH STREAMING and the settings.

8. Click on the text box under the download icon on the playback interface. You can select the local path to import the video file and PUBLISH STREAMING (default).

Considerations

MediaPlayerKitQuickstart only supports importing the local video files.

Implement MediaPlayer Kit

Prerequisites

• Xcode 10.12 or later.
• Physical macOS 10.12 or later.
• Ensure that your project has a validated provisioning profile certificate.

Integrate MediaPlayer Kit

1. Preparation

• Download and unzip Agora Native SDK. See the Video SDK in SDK Downloads.
• Make sure you have completed the integration of the Agora Native SDK, as described in Integrate Client.
• Download and unzip the MediaPlayerKit folder.

2. Create a project

• Open Xcode, Create a new Xcode project.
• On the Choose a template for your new project page, select macOS and cocoa App under Application, and click Next.
• Fill in your Product Name, such as "MediaPlayer", select Language for Objective-C, and click Next.
• Select the local path where the project file is stored, such as /Users/xxx/Desktop, click Create, and then you can see your project page.

3. Import files

• Right click on the "MediaPlayer" project file and click on Add Files to "MediaPlayer".
  • Import the AgoraRtcEngineKit.framework file:
    • Select the local path of this file;
    • Select Copy items if needed for Destination;
    • Select Create groups for Added folder;
    • Click on Add.
  • Import the MediaPlayerKit.framework file:
    • The import method is the same as that of the AgoraRtcEngineKit.framework file.
• Right click on the "MediaPlayer" file and click on Add Files to "MediaPlayer".
  • Import the Agora_MediaPlayer_Kit file:
    • The import method is the same as that of the AgoraRtcEngineKit.framework file.

4. Import libraries

• Click Build Phases, expand Link Binary With Libraries, and you can see the libraries that have been filled in after importing the files:
  • MediaPlayerKit.framework
  • liblibyuv.a
  • AgoraRtcEngineKit.framework

Make sure that these three libraries are added, otherwise go back to Step 3.

• Click on the "+" icon to add the following 21 libraries:
  • Carbon.framework
  • ForceFeedback.framework
  • IOKit.framework
  • libbz2.tbd
  • libiconv.2.4.0.tbd
  • QuartzCore.framework
  • SecurityFoundation.framework
  • CoreImage.framework
  • OpenGL.framework
  • OpenCL.framework
  • CoreVideo.framework
  • SystemConfiguration.framework
  • libresolv.tbd
  • libc++.tbd
  • libz.tbd
  • CoreAudio.framework
  • CoreWLAN.framework
  • CoreMedia.framework
  • AudioToolbox.framework
  • VideoToolbox.framework
  • AVFoundation.framework

5. Configure the library path

• Find Header Search Paths:

  • Click Build Settings;
  • Select All and Levels;
  • Fill in the search bar with Header Search Paths.

• Click Header Search Paths and add the path of the libyuv.h file:

  • Expand on the left side of the project page and find Agora_MediaPlayer_Kit > third_party > libyuv > include > libyuv.h file under the "MediaPlayer" file;

    • Right click here to select Show in Finder, you can see that the local absolute path of the libyuv.h file is /Users/xxx/Desktop/MediaPlayer/MediaPlayer/Agora_MediaPlayer_Kit/third_party_libyuv/include;

      /Users/xxx/Desktop/MediaPlayer is your project path, $(PROJECT_DIR).

    • Fill in the local relative path of the libyuv.h file: $(PROJECT_DIR)/MediaPlayer/Agora_MediaPlayer_Kit/third_party_libyuv/include.

6. Compile the project

• Click on the upper left triangle symbol in the Xcode interface to build the project.
• After a successful compilation, a window pops up.

You can refer to Call the interfaces or API documentation to complete your project.

Call the interfaces

API sequence diagram

• The diagram shows only the basic interfaces. If you have more complex requirements, you can also call more interfaces in the Agora Native SDK, such as enableDualStreamMode.
• Because setVideoView in the MediaPlayer Kit interface can set the local video window, you don't need to call setupLocalVideo in the Agora Native SDK interface beforehand.

1. Call the Agora Native SDK interface to complete initialization and the basic video setup.

   • Call the shareEngineWithAppId method to create and initialize an AgoraRtcEngineKit instance. See Implementation.
   • Call the setChannelProfile method to set the channel profile as Live Broadcast. See Set the channel profile as Live Broadcast.
   • Call the setClientRole method to set the role as the host.

     [self.agoraKit setClientRole:AgoraClientRoleBroadcaster]

   • Call the enableVideo method to enable the video mode. See Enable the video mode.

2. Call the MediaPlayer Kit interface to complete initialization and other preparations.

   • Call the shareInstance and createMediaPlayerKitWithRtcEngine() methods to create and initialize a MediaPlayer Kit instance.

     [[MediaPlayerKit shareInstance] createMediaPlayerKitWithRtcEngine:agoraKit withSampleRate:44100];

   • Call the MediaPlayerKitDelegate method to set the delegate method. See API documentation for details.

     [MediaPlayerKit shareInstance].delegate = self;

   • Call the setVideoView method to set the local view.

     [[MediaPlayerKit shareInstance] setVideoView:self.view];

3. Call the Agora Native SDK interface to complete the channel management.

   • Call the joinChannelByToken method to join the channel. See Join a live broadcast channel.

     Call this method after the setVideoView method.

   • Call the setupRemoteVideo method to set the view of the remote user.

4. Call the MediaPlayer Kit interface to load the video.

   • Call the load method to load the video into the memory.

     You can load the video from the local or URL path to meet your requirements. See Supported format.

     [[MediaPlayerKit shareInstance] load:url isAutoPlay:true/false];

5. Call the MediaPlayer Kit interface to complete the media player functions.

   • Call the play, adjustPlaybackSignalVolume, seekTo, getCurrentPosition, pause, and resume methods to adjust the media player in real time.

     You can learn about these methods by referring to API documentation.

     [[MediaPlayerKit shareInstance] play];
     [[MediaPlayerKit shareInstance] adjustPublishSignalVolume:volume];
     [[MediaPlayerKit shareInstance] seekTo:msec];
     [[MediaPlayerKit shareInstance] getCurrentPosition];
     ...

6. Call the MediaPlayer Kit interface to publish the audio/video to the remote user.

   • If you only want to publish the audio to the remote user:

     • Call the publishAudio method to publish the audio.

       [[MediaPlayerKit shareInstance] publishAudio];

     • Adjust the media player in real time by calling the interfaces in Step 5.

     • Call the adjustPublishSignalVolume method to adjust the volume received by the remote user.

       [[MediaPlayerKit shareInstance] adjustPublishSignalVolume:<#(int)#>];

     • Call the unpublishAudio method to stop publishing the audio to the remote user.

       [[MediaPlayerKit shareInstance] unpublishAudio];

   • If you want to publish the video to the remote user:

     • Call the publishVideo method to publish the video.

       [[MediaPlayerKit shareInstance] publishVideo];

     • Adjust the media player in real time by calling the interfaces in Step 5.

     • Call the adjustPublishSignalVolume method to adjust the volume received by the remote user.

       [[MediaPlayerKit shareInstance] adjustPublishSignalVolume:<#(int)#>];

     • Call the unpublishVideo method to stop publishing the video to the remote user.

       [[MediaPlayerKit shareInstance] unPublishVideo];

7. Call the MediaPlayer Kit interface to stop playback and quit MediaPlayer Kit.
   • Call the stop method to stop the playback.

     [[MediaPlayerKit shareInstance] stop];

   • Call the unload method to release the video loaded into the memory.

     [[MediaPlayerKit shareInstance] unload];

   • Call the destroy method to destroy the MediaPlayerKit instance and quit MediaPlayer Kit.

     After calling the destroy method, the binding of the display view of the local video stream is not valid.

     [[MediaPlayerKit shareInstance] destroy];

API documentation

See API documentation.

Consideration

If you get an error in MediaPlayer Kit when playing video from the URL path due to network problems, you need to call the load method again to reload the video after the network conditions improve.