ZegoMediaPlayer

Overview

The ZegoMediaPlayer component allows you to play audio and video media files and publish audio and video streams of these files.

Application scenarios

• Play test audio: Use ZegoMediaPlayer to play test audio, so as to check whether your audio device is working properly.
• Play background music: Use ZegoMediaPlayer to play music, mix it in a stream, and publish the stream to a remote user.
• Play videos: Capture video data by using a custom method and publish it, so that the remote user can pull it.

Supported formats

ZegoMediaPlayer supports the following formats by default: MP3, MP4, FLV, WAV, AAC, M3U8, and FLAC. It can play music from iPod Media Library (ipod-library://). If you need support for other formats, contact ZEGOCLOUD technical support.

Supported protocols

HTTP and HTTPS protocols are supported.

Download sample code

Download the sample source code as instructed in Download sample source code.

For more information about source code, see the files in the “/ZegoExpressExample/Examples/Others/MediaPlayer” directory.

Prerequisites

Before you implement the ZegoMediaPlayer feature, make sure that the following conditions are met:

• A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - How to view project information .
• ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Integrate the SDK and Implement a basic video call.

Procedure

1. Create a ZegoMediaPlayer instance

To create a ZegoMediaPlayer instance, call the createMediaPlayer operation of ZegoExpressEngine. A ZegoMediaPlayer instance can play one audio or video only. To play multiple media resources, you can create up to four ZegoMediaPlayer instances. If you call the operation when there are four instances already, nil will be returned.

• Sample API call

  ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];
  
  if (mediaPlayer) {
      self.mediaPlayer = mediaPlayer;
  } else {
      NSLog(@"Failed to create the player.");
  }

2. (Optional) Configure the event callback for the ZegoMediaPlayer instance

3. Load a media resource

To specify a media resource to play, call the loadResource operation of ZegoMediaPlayer. The value can be the absolute path of a local resource or the URL of a network resource, such as http://your.domain.com/your-movie.mp4.

• Sample API call

  // Obtain the absolute path of the `sample.mp4` file in the app package.
  NSString *fileURL = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"mp4"];
  
   // Load the resource. You can pass in either the absolute path of a local resource or the URL of a network resource.
  [self.mediaPlayer loadResource:fileURL callback:^(int errorCode) {
      // Execute a logic such as UI update.
      if (errorCode == 0) {
           // File loaded successfully. You can start playing the media resource.
           // [self.mediaPlayer start];
      }
  }];

To load binary audio data, call the loadResourceFromMediaData operation of ZegoMediaPlayer. You can obtain the data loading result by passing in callback parameters.

• Sample API call

   // Load the resource. Pass in the binary audio data to load and the start position.
  [self.mediaPlayer loadResourceFromMediaData:data startPosition:0L callback:^(int errorCode) {
      // Execute a logic such as UI update.
      if (errorCode == 0) {
           // File loaded successfully. You can start playing the media resource.
          // [self.mediaPlayer start];
      }
  }];

4. Control the playback

Playback status control

After successfully loading the file by calling the loadResource operation, call the start, pause, resume, or stop operation to start, pause, resume, or stop the playback. Once the player status is updated, the stateUpdatecallback of ZegoMediaPlayer will be triggered.

You can call the currentState operation to obtain the current status of the ZegoMediaPlayer instance.

If you set enableRepeat to YES, the ZegoMediaPlayer instance plays the file on repeat.

// Specify whether to play a file on repeat.
[self.mediaPlayer enableRepeat:YES];
// Start playing the file after calling the corresponding operation to load the file.
[self.mediaPlayer start];
// Pause the playback.
[self.mediaPlayer pause];
// Resume the playback.
[self.mediaPlayer resume];
// Stop the playback.
[self.mediaPlayer stop];

Player status change diagram：

Playback progress control

The mediaPlayer:playingProgress method for obtaining the playback progress is triggered by default once every 1,000 ms, and you call the setProgressIntervaloperation to modify the interval.

You can also call the currentProgress operation to obtain the current playback progress.

You can call the seekTo operation to adjust the playback progress.

• Sample API call

  // Set the playback callback interval to 1,000 ms, that is, a callback is received once every 1,000 ms.
  [self.mediaPlayer setProgressInterval:1000];
  
  // Obtain the total duration of the media file being played, in ms.
  unsigned long long totalDuration = self.mediaPlayer.totalDuration;
  
  // Obtain the playback progress, in ms.
  unsigned long long progress = self.mediaPlayer.currentProgress;
  
  NSLog(@"process: %llu", progress);
  
  // Change the playback progress to half of the total duration, in ms.
  [self.mediaPlayer seekTo:totalDuration/2 callback:^(int errorCode) {
      NSLog(@"errorCode: %d", errorCode);
  }];

Playback speed control

After loading the resource, call the setPlaySpeed operation to set the playback speed.

• Sample API call

  // Set the playback speed only after loading the resource.
  // Set the playback speed to 2x.
  [self.mediaPlayer setPlaySpeed:2.0];

Audio playback control

To obtain or set the playback volume, call the playVolume or setPlayVolume operation.

To obtain or set the stream publishing volume, call the publishVolume orsetPublishVolume operation.

To mix the audio to the stream being published, call theenableAuxoperation.

To mix the audio to the stream with the local speaker being muted, call the muteLocale operation.

// Obtain the playback volume of the ZegoMediaPlayer instance.
int playVolume = self.mediaPlayer.playVolume;

// Half the playback volume.
[self.mediaPlayer setPlayVolume:playVolume/2];

// Obtain the stream publishing volume of the ZegoMediaPlayer instance.
int publishVolume = [self.mediaPlayer publishVolume];

// Set the stream publishing volume of the ZegoMediaPlayer instance.
[self.mediaPlayer setPublishVolume:publishVolume];

// Enable audio mixing to the stream being published.
[self.mediaPlayer enableAux:YES];

// Enable muting the local speaker.
[self.mediaPlayer muteLocal:YES];

To obtain the audio data of the file, call the setAudioHandler operation to set the audio frame callback.

• Sample API call

  // Call the `set` operation of the ZegoMediaPlayer instance.
  [self.mediaPlayer setAudioHandler:self];

  // Player audio frame callback.
  // @param mediaPlayer
  // @param data The raw data of the audio frame.
  // @param dataLength Data length.
  // @param param The parameters of the audio frame.
  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer audioFrameData:(const unsigned char *)data dataLength:(unsigned int)dataLength param:(ZegoAudioFrameParam *)param {
  // The audio frame callback of ZegoMediaPlayer is received.
  }

Video playback control

To set the display view of a video resource being played, call the setPlayerCanvas operation.

• Sample API call

  // Set the playback view.
  [self.mediaPlayer setPlayerCanvas:[ZegoCanvas canvasWithView:self.mediaPlayerView]];

To obtain the video data of the file, call the setVideoHandler operation to set the video frame callback.

• API prototype

  // Set the video frame callback, frame data format, and data type.
  - (void)setVideoHandler:(nullable id<ZegoMediaPlayerVideoHandler>)handler format:(ZegoVideoFrameFormat)format type:(ZegoVideoBufferType)type;

  @protocol ZegoMediaPlayerVideoHandler <NSObject>
  
  @optional
  
  // The callback for the raw data of the video frame of the ZegoMediaPlayer instance.
  // @param mediaPlayer
  // @param data The raw data of the video frame, for example, for RGBA videos, consider data[0]; for I420 videos, consider data[0,1,2].
  // @param dataLength Data length, for example, for RGBA videos, consider dataLength[0]; for I420 videos, consider dataLength[0,1,2].
  // @param param The parameters of the video frame.
  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFrameRawData:(const unsigned char * _Nonnull * _Nonnull)data dataLength:(unsigned int *)dataLength param:(ZegoVideoFrameParam *)param;
  
  // The `CVPixerBuffer` data callback for the video frame of the ZegoMediaPlayer instance.
  // @param mediaPlayer
  // @param buffer Video frame data encapsulated as `CVPixerBuffer`.
  // @param param The parameters of the video frame.
  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFramePixelBuffer:(CVPixelBufferRef)buffer param:(ZegoVideoFrameParam *)param;
  
  @end

• Sample API call

  // Set the video format to `NV12` and data type to `CVPixelBuffer`.
  [self.mediaPlayer setVideoHandler:self format:ZegoVideoFrameFormatNV12 type:ZegoVideoBufferTypeCVPixelBuffer];

  // The `CVPixerBuffer` data callback for the video frame of the ZegoMediaPlayer instance.
  // @param mediaPlayer
  // @param buffer Video frame data encapsulated as `CVPixerBuffer`.
  // @param param The parameters of the video frame.
  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFramePixelBuffer:(CVPixelBufferRef)buffer param:(ZegoVideoFrameParam *)param {
  // NSLog(@"pixel buffer video frame callback. format:%d, width:%f, height:%f", (int)param.format, param.size.width, param.size.height);
  }

Video stream publishing

1. Before publishing the video stream in the ZegoMediaPlayer instance, you need to call the setVideoHandler operation to configure video frame callback listening, so as to obtain the video frame data thrown by videoFrameRawData or videoFramePixelBuffer.

2. For more information about capturing video data by using a custom method and mixing the data to a stream, see Custom video capture.

3. You need to add a judgment logic for flag tovideoFrameRawData or videoFramePixelBuffer. If flag is set to True (that is, the onStart, call the sendCustomVideoCapturePixelBuffer method to send the obtained video data to the ZIM SDK.

4. Call the startPublishingStream operation to start stream publishing as instructed in "Stream publishing" in Quick start - Implementation process.

Voice changing

Call the setVoiceChangerParam operation of ZegoMediaPlayer in scenarios where voice changing is required, for example, changing the pitch of accompaniment in karaoke. You can change the voice by setting the pitch parameter in the ZegoVoiceChangerParamobject. The value range is [-12.0, 12.0]. The larger the value, the higher the pitch. The default value is 0.0, which indicates to disable voice changing.

ZegoVoiceChangerParam *param = [[ZegoVoiceChangerParam alloc] init];
// Male-to-baby voice changing.
param.pitch = 8.0f; 
// Male-to-female voice changing.    
param.pitch = 4.0f; 
// Female-to-baby voice changing.    
param.pitch = 6.0f; 
// Female-to-male voice changing.    
param.pitch = -3.0f;    
[self.mediaPlayer setVoiceChangerParam:param audioChannel:ZegoMediaPlayerAudioChannelAll];

5. Destroy the ZegoMediaPlayer instance

Destroy the ZegoMediaPlayer instance that is no longer in use to release occupied resources. Below is a sample API call:

self.mediaPlayer = nil;

FAQ

1. How can I change the resource being played?

Call the stop operation and then call the loadResource operation again to load a new resource.