Live Streaming
  • iOS : Objective-C
  • Android
  • Web
  • Flutter
  • React Native
  • Electron
  • Unity3D
  • Windows
  • macOS
  • Linux
  • Overview
  • Live Streaming vs. Interactive Live Streaming
  • Develop your app
    • Live Streaming
      • Integrate the SDK
      • Implement a basic live streaming
      • Enhance basic livestream
      • CDN
      • Play live streams
    • Interactive Live Streaming
  • Upgrade the livestream
    • Advanced features
      • Media push
        • Mix the live streams
      • Enhance the livestream
        • Share the screen
        • Improve your appearance in the livestream
        • Beautify & Change the voice
        • Output the livestream in H.265
        • Watermark the live/Take snapshots
        • Config video codec
        • Visualize the sound level
      • Message signaling
        • Convey extra information using SEI
        • Broadcast real-time messages to a room
        • Quotas and limits
      • Ensure livestream quality
        • Test network and devices in advance
        • Check the room connection status
        • Monitor streaming quality
        • Configure bandwidth management
      • Play media files
        • Play media files
        • Play sound effects
      • Record video media data
      • Join multiple rooms
      • Publish multiple live streams
      • Low-latency live streaming
      • Use the bit mask
      • Common audio config
      • Playing streams via URL
    • Distincitve features
      • Set the voice hearing range
      • Single stream transcoding
      • Low-light enhancement
      • Customize the video and audio
  • Upgrade using Add-on
  • Resources & Reference
    • SDK
    • Sample code
    • API reference
      • Client APIs
      • Server APIs
    • Debugging
      • Error codes
    • FAQs
    • Key concepts
  • Documentation
  • Live Streaming
  • Upgrade the livestream
  • Advanced features
  • Play media files
  • Play media files

ZegoMediaPlayer

Last updated:2024-01-11 19:25

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:

  • ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Quick start .
  • A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information .

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

Configuration of the event callback for the ZegoMediaPlayer instance To configure the event callback for the ZegoMediaPlayer instance, call the [`setEventHandler`\|\_blank](/zh/api?doc=Express_Video_SDK_API~ObjectiveC~class~zego-media-player#set-event-handler) operation of ZegoMediaPlayer, so as to receive notifications for player status change, player network status update, and playback progress change.
  • Sample API call

    //
    [self.mediaPlayer setEventHandler:self];
    // Player status callback.
    
    // @param mediaPlayer
    // @param state Player status.
    // @param errorCode Error code. For more information, see the document on common error codes.
    - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer stateUpdate:(ZegoMediaPlayerState)state errorCode:(int)errorCode {
        switch (state) {
            case ZegoMediaPlayerStateNoPlay:
                // Playback stopped.
                break;
            case ZegoMediaPlayerStatePlaying:
                // Playing.
                break;
            case ZegoMediaPlayerStatePausing:
                // Playback paused.
                break;
            case ZegoMediaPlayerStatePlayEnded:
                // Playback of the current resource is complete, and you can play the next resource.
                break;
        }
    }
    
    // The callback for the player network status.
    
    // @param mediaPlayer
    // @param networkEvent Network status event.
    - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer networkEvent:(ZegoMediaPlayerNetworkEvent)networkEvent {
        if (networkEvent == ZegoMediaPlayerNetworkEventBufferBegin) {
            // Display the loading UI.
        } else if (networkEvent == ZegoMediaPlayerNetworkEventBufferEnded) {
            // Close the loading UI.
        }
    }
    
    // Playback progress callback.
    
    // @param mediaPlayer
    // @param millisecond Progress, in ms.
    - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer playingProgress:(unsigned long long)millisecond {
        // Update the progress.
    }

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];
        }
    }];

If you are playing a previously loaded media file, call the stop operation to stop the playback before calling the loadResource operation to load the new media resource; otherwise, loading fails.

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 use audio mixing, you must call the Set microphone permissions operation. To mute the microphone, call the muteMicrophone operation.

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);
    }

If type is set to ZegoVideoBufferTypeCVPixelBuffer, format can be set to ZegoVideoFrameFormatI420, ZegoVideoFrameFormatNV12, ZegoVideoFrameFormatBGRA32, or ZegoVideoFrameFormatARGB32 only. If you set format to another value, no video frame data will be called back.

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.

When you capture data by using a custom method, we recommend that you define a flag.

  • If the onStart callback is triggered, set flag to True, indicating to start sending the video data captured by using a custom method to the ZIM SDK.
  • If theonStop callback is triggered, set flag to False, indicating to stop sending the captured video data to the ZIM SDK.
  1. 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.

  2. 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;
If the reference count of the ZegoMediaPlayer instance is `0`, the instance will be destroyed and resources occupied by it will be released.

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.

Page Directory