logo
ConsoleSign Up
Document
Client API
Server API
Live Streaming
React Native: JS
Introduction
Overview
Features
Client SDK
Download SDK
Release Notes
Common Error Codes
Quick Start
Live Streaming
Communication
Room Features
Audio
Video
Other Features
Best Practices
FAQ
On this page

Media Player

2024-07-27

Feature Overview

The media player component provides the ability to play audio and video media files, and also supports pushing the audio and video data of the played media files to the stream.

Application Scenarios

  • Playing test audio: You can use the media player to play test audio and verify whether the audio playback device is working properly.
  • Playing background music: Use the media player to play music and mix it into the stream so that remote users can hear the background music.
  • Playing video files: Combine with custom video capture functionality to push the video data of media resources to the stream, so remote users can play and watch it.

Supported Formats

The media player supports the following formats and protocols by default:

Video Codec Formats:

  • H263, H264, H265, MPEG4, MJPEG

Audio Codec Formats:

  • AAC, MP2, MP3, FLAC, WMA V1, WMA V2, PCM, AC3, EAC3

Container Formats:

  • WAV, FLAC, MP3, MP4, MOV, MPEG-TS, FLV, Matroska (MKV), AVI, ASF, JPEG

Supported Protocols:

  • HTTP, HTTPS, HLS
Note

If you need support for other formats, please contact ZEGOCLOUD Technical Support.

Download Sample Source Code

Please refer to Download Sample Source Code.

For related source code, please check the "App.js" file.

Prerequisites

Before using the media player, please ensure:

Usage Steps

1 Create Media Player

Call the createMediaPlayer interface of ZegoExpressEngine to create a media player instance. A media player instance can only play one audio or video. The engine supports creating up to 10 player instances at the same time to achieve the effect of playing multiple media resources simultaneously. If there are already 10 player instances, calling the create player interface again will return null.

  • Call example:

    ZegoExpressEngine.instance().createMediaPlayer().then((player) => {
  this.mediaPlayer = player;
});

2 (Optional) Set Event Callbacks for Player

Call the on interface of the media player to set event callbacks for the player to receive notifications such as "player playback state changes", "player network status updates", "player playback progress changes", etc.

  • Interface prototype:

    export abstract class ZegoMediaPlayer {

/**
 * Listen to player event notifications
 *
 * @param event Event type
 * @param callback Method triggered after event is sent
 */
abstract on<MediaPlayerEventType extends keyof ZegoMediaPlayerListener>(event: MediaPlayerEventType, callback: ZegoMediaPlayerListener[MediaPlayerEventType]): void;
......
}
    export interface ZegoMediaPlayerListener {
/**
 * @event ZegoMediaPlayer#onMediaPlayerStateUpdate
 * @desc Player playback state callback
 *
 * @property {ZegoMediaPlayer} mediaPlayer - Callback player instance
 * @property {ZegoMediaPlayerState} state - Player state
 * @property {number} errorCode - Error code, please refer to common error code document /real-time-video-rn/error-code.html for details
 */
mediaPlayerStateUpdate: (mediaPlayer: ZegoMediaPlayer, state: ZegoMediaPlayerState, errorCode: number) => void;

/**
 * @event ZegoMediaPlayer#onMediaPlayerNetworkEvent
 * @desc Player network status event callback
 *
 * @property {ZegoMediaPlayer} mediaPlayer - Callback player instance
 * @property {ZegoMediaPlayerNetworkEvent} networkEvent - Network status event
 */
mediaPlayerNetworkEvent: (mediaPlayer: ZegoMediaPlayer, networkEvent: ZegoMediaPlayerNetworkEvent) => void;

/**
 * @event ZegoMediaPlayer#onMediaPlayerPlayingProgress
 * @desc Player playback progress callback
 *
 * @property {ZegoMediaPlayer} mediaPlayer - Callback player instance
 * @property {number} millisecond - Progress in milliseconds
 */
mediaPlayerPlayingProgress: (mediaPlayer: ZegoMediaPlayer, millisecond: number) => void;
}

  • Call example:

    this.mediaPlayer.on("mediaPlayerStateUpdate", (player, state, errorCode) => {
    switch (state) {
        case ZegoMediaPlayerState.NoPlay:
            // Playback stopped state
            break;
        case ZegoMediaPlayerState.Playing:
            // Playing state
            break;
        case ZegoMediaPlayerState.Pausing:
            // Paused state
            break;
        case ZegoMediaPlayerState.PlayEnded:
            // Current track playback completed, can perform operations such as playing next track
            break;
    }
  });

3 Load Media Resources

Call the media player's loadResource to specify the media resource to play, which 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. Users can get the result of loading files by passing in callback parameters.

Warning

If the media resource has already been loaded by loadResource or is playing, please call the stop interface to stop playback first, and then call the loadResource interface to load media resources, otherwise it cannot be loaded successfully.

  • Interface prototype:

    // Load resource, can pass absolute path of local resource or URL of network resource
abstract loadResource(path: string): Promise<ZegoMediaPlayerLoadResourceResult>;

  • Call example:

    // This example shows getting the absolute path of the sample.mp4 file in the App package
this.mediaPlayer.loadResource("sample.mp4").then((ret) => {
    console.log("load resource error: " + ret.errorCode);
  });

4 Playback Control

Playback State Control

After successfully loading the file by calling loadResource, you can call start , pause , resume , stop to start and stop playback. Once the internal state of the player changes, the mediaPlayerStateUpdate callback will be triggered.

Developers can also call getCurrentState at any time to get the current state of the player.

If enableRepeat is set to "YES", the player will automatically replay after finishing playing the file.

  • Call example:

    export abstract class ZegoMediaPlayer {

    // Load media resource
    abstract loadResource(path: string): Promise<ZegoMediaPlayerLoadResourceResult>;

    // Start playing (need to load resource before playing)
    abstract start(): Promise<void>;

   // Stop playing
    abstract stop(): Promise<void>;

    // Pause playing
    abstract pause(): Promise<void>;

   // Resume playing
    abstract resume(): Promise<void>;

    ......
   }

Playback Progress Control

The progress of playing the file will be called back through the mediaPlayerPlayingProgress interface. The default interval for triggering the callback is 1000 ms. You can change this interval through setProgressInterval .

Developers can also use getCurrentProgress to get the current playback progress.

The playback progress can be adjusted through the seekTo interface.

  • Interface prototype:

    export abstract class ZegoMediaPlayer {

}
@interface ZegoMediaPlayer : NSObject

/// Total playback duration of the entire file in milliseconds
abstract getTotalDuration(): Promise<number>;

/// Current playback progress in milliseconds
abstract getCurrentProgress(): Promise<number>;

......

/// Set specified playback progress in milliseconds
abstract seekTo(millisecond: number): Promise<ZegoMediaPlayerSeekToResult>;

......

/// Set playback progress callback interval
abstract setProgressInterval(millisecond: number): Promise<void>;

......

@end

  • Call example:

    this.mediaPlayer.setProgressInterval(1000)

var totalDuration = await this.mediaPlayer.getTotalDuration()

await this.mediaPlayer.seekTo(totalDuration/2);
var progress = await this.mediaPlayer.getCurrentProgress()

NSLog(@"process: %llu", progress);

Playback Speed Control

After loading the resource, users can set the current playback speed through setPlaySpeed.

  • Call example

    // Set 2x playback speed, playback speed range is 0.5 ~ 4.0, default is 1.0
await this.mediaPlayer.setPlaySpeed(2.0);

Player Audio Control

Get and control playback volume through getPlayVolume and setPlayVolume interfaces.

Get and control publishing stream volume through getPublishVolume and setPublishVolume interfaces.

Call the enableAux interface to mix the sound of the file into the stream being published.

Note

If you want to use the sound mixing capability, you must set microphone permissions. If you do not want to record microphone sound, you can mute the microphone through muteMicrophone.

Call the muteLocal interface to enable local silent playback but still be able to mix sound into the stream normally.

  • Call example:

    // Get player's current playback volume
var playVolume = await this.mediaPlayer.getPlayVolume;

// Set player volume to half of original
this.mediaPlayer.setPlayVolume(playVolume/2);

// Get player's current publishing stream volume
var publishVolume = await  this.mediaPlayer.getPublishVolume();

// Set player publishing stream volume
this.mediaPlayer.setPublishVolume(80.0);

// Enable mixing resource sound into the stream being published
this.mediaPlayer.enableAux(true);

// Enable local silent playback
this.mediaPlayer.muteLocal(true);

Player Video Control

Note

Operations in this section only apply to audio and video scenarios. No setting is required for pure audio scenarios.

When playing video resources, use the setPlayerView interface to set the video display view.

  • Interface prototype:

    // Set player view
abstract setPlayerView(view: ZegoView): Promise<void>;

  • Call example:

    this.mediaPlayer.setPlayerView({"reactTag": findNodeHandle(this.refs.zego_media_view), "viewMode": 0, "backgroundColor": 0});

render() {
return (
  <>
    <StatusBar barStyle="dark-content" />
    <SafeAreaView>
          <View style={{height: 200}}>
              <ZegoTextureView ref='zego_media_view' style={{height: 200}}/>
          </View>
    </SafeAreaView>
  </>
);
}
}

5 Destroy Media Player

After using the media player, you need to call the destroyMediaPlayer interface in time to destroy the player instance variable and release occupied resources.

  • Call example:

    ZegoExpressEngine.instance().destroyMediaPlayer(this.mediaPlayer)

FAQ

How to switch playback resources during playback?

First call the player's stop interface, then call the loadResource interface again to load the new resource.

Previous

H.265

Next

Audio and Video Recording

On this page

Back to top