Media player

Introduction

The media player component of the ZEGO Express SDK provides the following abilities:

• Play audio and video files.
• Simultaneously stream out the audio/video data of the media file being played

This document describes how to use the media player in your apps.

Use cases

You can use the media player for various use cases. The following are some typical examples:

• Verify audio output device: play test audio to verify that the audio playback device is working correctly.
• Play background music: play and stream audio to remote users so that you can add background music to your live stream.

Supported media file formats

The media player supports MP3, MP4, FLV, WAV, AAC, M3U8 formats. You can also use the media player to play the music from the iOS media library (ipod-library://).

Supported protocols

The media player supports playing media resources from the internet over the HTTP or HTTPS protocol.

Prerequisites

Before you begin to use the media player in your project, make sure you complete the following steps:

• 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.

Create media player instances

To create a media player instance, call the createMediaPlayer method of the engine (the ZegoExpressEngine instance you create when initializing the SDK).

A media player instance can only play one audio and video source at a time. You can create up to 4 media player instances to play multiple media resources at the same time. If there are already 4 media player instances running, calling this method will return nil.

• Function prototype:

  /// Create a media player instance
  ///
  /// The ZegoExpressEngine class supports up to 4 media player instances. If there are already 4 media player instance running, calling this method returns `nil`.
  /// @return: The returned media player instance. 
  
  - (nullable ZegoMediaPlayer *)createMediaPlayer;

• Sample code:

  ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];
  
  if (mediaPlayer) {
      self.player = mediaPlayer;
  } else {
      NSLog(@"createMediaplayer failed.");
  }

Optional: Listen for and handle media player events

Load a media resource

• Before you play a media resource, call the media player's loadResource method to load the resource first. According to the actual situation, you can pass the absolute path of a local resource or the URL (for example, http://your.domain.com/your-movie.mp4) of a network resource to the path parameter. To obtain the result of the resource loading, pass in a callback parameter.

• If you want to play a binary audio, call the loadResourceFromMediaData method the load the audio resource. To obtain the result of the resource loading, pass in a callback parameter.

• Function prototype:

  /// Load a media resource. Pass in the absolute path to a local resource or the URL of a network resource.
  - (void)loadResource:(NSString *)path callback:(nullable ZegoMediaPlayerLoadResourceCallback)callback;

  /// Load a binary audio resource. Pass in the binary audio data and the starting position.
  - (void)loadResourceFromMediaData:(NSData *)mediaData startPosition:(long)startPosition callback:(nullable ZegoMediaPlayerLoadResourceCallback)callback;

• Sample code:

  // Obtain the absolute path to the file sample.mp4 in the app package.
  NSString *fileURL = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"mp4"];
  
  [self.player loadResource:fileURL callback:^(int errorCode) {
      // Update the application UI accordingly.
  }];

  
  [self.player loadResourceFromMediaData:data startPosition:0L callback:^(int errorCode) {
      // Update the application UI accordingly.
  }];

Control the playback

Control the playback status

Call the media player's methods start, pause, resume, and stop to control the playback.

When you execute these operations, the internal state of the media player changes accordingly, and the mediaPlayer:stateUpdate callback will be triggered.

You can also access the media player's currentState property to get the current state of the media player at any time.

If you set enableRepeat to YES, the media player will automatically repeat playing the loaded media resource.

@interface ZegoMediaPlayer : NSObject

......

/// Start playing the media resource (load the resource first)
- (void)start;

/// Stop the playback
- (void)stop;

/// Pause the playback
- (void)pause;

/// Resume the playback
- (void)resume;

/// Whether to repeat playing the media resource
- (void)enableRepeat:(BOOL)enable;

......

@end

Control the playback progress

The playback progress can be obtained through the callback mediaPlayer:playingProgress, which is triggered at an interval of 1,000 ms by default. You can change the callback interval by calling the media player's setProgressInterval method.

You can access the media player's currentProgress property to get the current playback progress at any time.

To adjust the playback progress, call the media player's seekTo method with the target time point.

• Function prototype:

  @interface ZegoMediaPlayer : NSObject
  
  /// The duration of the media file, in milliseconds.
  @property (nonatomic, assign, readonly) unsigned long long totalDuration;
  
  /// The current playback progress, in milliseconds.
  @property (nonatomic, assign, readonly) unsigned long long currentProgress;
  
  ......
  
  /// Seek to the specified time point, in milliseconds.
  - (void)seekTo:(unsigned long long)millisecond callback:(nullable ZegoMediaPlayerSeekToCallback)callback;
  
  ......
  
  /// Set the progress callback interval.
  - (void)setProgressInterval:(unsigned long long)millisecond;
  
  ......
  
  @end

• Sample code:

  [self.player setProgressInterval:1000];
  
  unsigned long long totalDuration = self.player.totalDuration;
  
  [self.player seekTo:totalDuration/2 callback:^(int errorCode) {
      NSLog(@"errorCode: %d", errorCode);
  }];
  
  unsigned long long progress = self.player.currentProgress;
  
  NSLog(@"process: %llu", progress);

Control the playback speed

After you loaded the resource, you can call the setPlaySpeed method to set the playback speed.

• Function prototype:

  /// Set the playback speed.
  ///
  /// Version supported: 2.12.0 or later
  /// Description: Used for setting the playback speed.
  /// Execution time: After you loaded the resource.
  /// Restrictions: None
  /// API related: You can load the resource by calling the [loadResource] method.
  ///
  /// @param [speed] is the playback speed. Range from 0.5 -2.0. Default value is1.0
  - (void)setPlaySpeed:(float)speed;
  
  ......
  
  @end

• Sample code:

  // Set the playback speed to 2.0
  [self.player setPlaySpeed:2.0];

Control the audio

To get the local playback volume, access the media player's playVolume property.

To set the local playback volume, call the media player's setPlayVolume method.

To get the volume of the audio being streamed out, access the media player's playVolume property.

To set the volume of the audio being streamed out, call the media player's setPublishVolume method.

To mix the audio of the media resource being played into the stream being published, call the media player's enableAux method.

To mute or unmute the local playback, call the media player's muteLocal method. This doesn't affect the audio being published out simultaneously.

• Sample code

  // Get the current playback volume
  int playVolume = self.player.playVolume;
  
  // Set the playback volume to half of its original value
  [self.player setPlayVolume:playVolume/2];
  
  // Mix the audio of the media resource being played into the stream being published.
  [self.player enableAux:YES];
  
  // Mute the local playback.
  [self.player muteLocal:YES];

If you want to obtain the audio data of the media file being played, do the following:

1. Call the media player's setAudioHandler method to set up an audio event callback handler for the media player.
2. Listen for the mediaPlayer:audioFrameData callback to obtain the audio frame data the media player sends out.

• Function prototype:

  @interface ZegoMediaPlayer : NSObject
  ......
  /// Set up an audio event callback handler for the media player.
  - (void)setAudioHandler:(nullable id<ZegoMediaPlayerAudioHandler>)handler;
  ......
  @end

  @protocol ZegoMediaPlayerAudioHandler <NSObject>
  
  @optional
  
  /// The callback is triggered when the media player sends out audio frame data.
  /// @param mediaPlayer: The media player instance. 
  /// @param data: The audio frame raw data.
  /// @param dataLength: The length of the audio data.
  /// @param param: Audio frame parameter.
  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer audioFrameData:(const unsigned char *)data dataLength:(unsigned int)dataLength param:(ZegoAudioFrameParam *)param;
  
  @end

• Sample code:

  // Implement the `ZegoMediaPlayerAudioHandler` protocol and call the media player's `setAudioHandler` method.
  [self.player setAudioHandler:self];

  - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer audioFrameData:(const unsigned char *)data dataLength:(unsigned int)dataLength param:(ZegoAudioFrameParam *)param {
      // Process the audio frame data the media player sends out.
  }

Use the voice changer

In online karaoke use cases, if you need to change the pitch of the accompaniment, you can call the media player’s setVoiceChangerParam method to do so. By changing the value of the ZegoVoiceChangerParam parameter, you can raise or lower the pitch as needed. The value range of this parameter is [-12.0, 12.0]. As you increase the value, the pitch gets higher. The default value is 0.0, which means the voice changer is turned off.

ZegoVoiceChangerParam *param = [[ZegoVoiceChangerParam alloc] init];
param.pitch = 8.0f; /** Change an adult male voice into a child's voice. */
param.pitch = 4.0f; /** Change an adult male voice into an adult female voice. */
param.pitch = 6.0f; /** Change an adult female voice into a child's voice. */
param.pitch = -3.0f; /** Change an adult female voice into an adult male voice. */
[self.player setVoiceChangerParam:param audioChannel:ZegoMediaPlayerAudioChannelAll];

Destroy the media player instance

When a media player instance is no longer required, destroy it in time to release the occupied resources.

self.player = nil;

FAQ

1. How to switch media resources during playback?

   First, call the media player's stop method, and then call its loadResource method to load the new resource.