HJPlayer

English | 中文

This Library currently support play FLV steam video and HLS stream video(do not support decrypt) in browser environment; It relies on HTML5 video element and MediaSource Extensions BOM API. only with H264 codec and AAC codec;

Why we do this?

This spring we finish a new PC web project, It needs to play FLV stream video and HLS stream video stream in a browser page. First, we import flv.js and hls.js at the same time, flv.js plays FLV stream video, hls.js plays HLS stream video; It was certainly worked well, but the filesize of the javascript does not. After studying the flv.js and hls.js code, we find the same process of two libraries; They all have download, demuxer, remuxer, controller function, so we try to use the framework of flv.js to assemble the download, demuxer and remuxer function of hls.js library; It works!!!; The filesize is less than flv.js + hls.js, but it can do similar functions to play flv stream video and hls stream video; (not perfectly, still has some coincident codes, can be more smaller); Thanks to flv.js 和 hls.js;

How do this libary work?

When played flv stream video, loader downloads the flv stream data, and send data to FLVCodec module, FLVCodec module use the data to generates ISO BMFF (MP4) fragments - InitSegment(ftyp + moov) and MediaSegment(moof + mdat), and then sends them to Video Element through Media Source Extensions API and URLS API; When played hls stream video, based on flv process, loader module will parse the m3u8 document first;

Feature

1. play flv live stream and flv playback;
2. play hls live stream and hls playback;
3. Chrome, FireFox, Safari 10, IE11 and Edge worked well;

Installation

npm install hjplayer --save

build

npm install

npm run build

How to import

This library can import the way of ES6 Moudule

import HJPlayer from 'hjplayer'

or import through script src;

<script src="./dist/hjplayer.js">

Getting Started

flv

if (HJPlayer.isSupported()) {
    player = new HJPlayer({
        type: 'flv',
        url: 'http://xxx.xxx.com/xxxx.flv',
    }, {
        ...user config
    });
    player.attachMediaElement(videoElement);
    player.load();
    player.play();
}

HLS

if (HJPlayer.isSupported()) {
    player = new HJPlayer({
        type: 'm3u8',
        url: 'http://xxx.xxx.com/xxxx.m3u8',
    }, {
        ...user config
    });
    player.attachMediaElement(videoElement);
    player.load();
    player.play();
}

demo

demo

config

When init the player, it needs MediaConfig(@required) and userConfig(@optional) params;

MediaConfig

| field | type | Description | | ------------------ | --------------------- | ---------------------------------------- | | type | string | media type, 'flv' or 'mp4' or 'm3u8'| | isLive? | boolean | whether the media is a live stream | | cors? | boolean | Indicates whether to enable CORS for http fetching | | withCredentials? | boolean | Indicates whether to do http fetching with cookies | | hasAudio? | boolean | Indicates whether the stream has audio track | | hasVideo? | boolean | Indicates whether the stream has video track | | duration? | number | Indicates total media duration, in milliseconds | | filesize? | number | Indicates total file size of media file, in bytes | | url? | string | Indicates media URL, can be starts with 'https(s)' or 'ws(s)' (WebSocket flv only) | | segments? | Array<MediaSegment> | Optional field for multipart playback, see MediaSegment |

MediaSegment

If segments field exists, transmuxer will treat this MediaDataSource as a multipart source.

In multipart mode, duration filesize url field in MediaDataSource structure will be ignored.

MediaSegment Object :

| field | type | Description | | ----------- | -------- | ---------------------------------------- | | duration | number | Required field, indicates segment duration in milliseconds | | filesize? | number | Optional field, indicates segment file size in bytes | | url | string | Required field, indicates segment file URL |

segments demo

{
    type: 'flv',
    // Required
    "segments": [
        {
            "duration": 3333,  // in milliseconds
            "filesize": 4444,  // in bytes
            "url": "http://xxxx/segments-1.flv"
        },
        {
            "duration": 5555,
            "filesize": 6666,
            "url": "http://xxxx/segments-2.flv"
        },
        {
            "duration": 7777,
            "filesize": 8888,
            "url": "http://xxxx/segments-3.flv"
        }
        ...
    ]
}

userConfig

| field | type | default | Description | | -------------------------------- | --------- | ---------------------------- | ---------------------------------------- | | enableWorker? | boolean | false | Enable separated thread for transmuxing (unstable for now) | | enableStashBuffer? | boolean | true | Enable IO stash buffer. Set to false if you need realtime (minimal latency) for live stream playback, but may stalled if there's network jittering. | | FORCE_GLOBAL_TAG? | boolean | false | enable to use global tag HJPLAYER when console | | GLOBAL_TAG | string | HJPLAYER | default global tag | | ENABLE_CALLBACK | boolean | false | enable logger callback | | ENABLE_ERROR | boolean | true | enable console.error |
| ENABLE_INFO | boolean | false | enable console.info | | ENABLE_WARN | boolean | false | enable console.warn | | ENABLE_DEBUG | boolean | false | enable console.debug |
| stashInitialSize? | number | 384KB | Indicates IO stash buffer initial size. Default is 384KB. Indicate a suitable size can improve video load/seek time. | | isLive? | boolean | false | Same to isLive in MediaDataSource, ignored if has been set in MediaDataSource structure. flv only| | lazyLoad? | boolean | true | Abort the http connection if there's enough data for playback| | lazyLoadMaxDuration? | number | 3 * 60 | Indicates how many seconds of data to be kept for lazyLoad. | | lazyLoadRecoverDuration? | number | 30 | Indicates the lazyLoad recover time boundary in seconds. | | deferLoadAfterSourceOpen? | boolean | true | Do load after MediaSource sourceopen event triggered. On Chrome, tabs which be opened in background may not trigger sourceopen event until switched to that tab. | | autoCleanupSourceBuffer | boolean | false | Do auto cleanup for SourceBuffer | | autoCleanupMaxBackwardDuration | number | 3 * 60 | When backward buffer duration exceeded this value (in seconds), do auto cleanup for SourceBuffer | | autoCleanupMinBackwardDuration | number | 2 * 60 | Indicates the duration in seconds to reserve for backward buffer when doing auto cleanup. | | fixAudioTimestampGap | boolean | true | Fill silent audio frames to avoid a/v unsync when detect large audio timestamp gap. | | accurateSeek? | boolean | false | Accurate seek to any frame, not limited to video IDR frame, but may a bit slower. Available on Chrome > 50, FireFox and Safari. | | seekType? | string | 'range' | 'range' use range request to seek, or 'param' add params into url to indicate request range. | | seekParamStart? | string | 'bstart' | Indicates seek start parameter name for seekType = 'param' | | seekParamEnd? | string | 'bend' | Indicates seek end parameter name for seekType = 'param' | | rangeLoadZeroStart? | boolean | false | Send Range: bytes=0- for first time load if use Range seek | | customSeekHandler? | object | undefined | Indicates a custom seek handler | | reuseRedirectedURL? | boolean | false | Reuse 301/302 redirected url for subsequence request like seek, reconnect, etc. | | referrerPolicy? | string | no-referrer-when-downgrade | Indicates the Referrer Policy when using FetchStreamLoader | | headers? | object | undefined | Indicates additional headers that will be added to request | HLS config. | | tsAutoLevelChoose? | boolean | false | when play hls. whether auto choose the suitable bitrate level | | maxFragLookUpTolerance? | float | 0.25 | This tolerance factor is used during fragment lookup. Instead of checking whether buffered.end is located within [start, end] range, frag lookup will be done by checking within [start-maxFragLookUpTolerance, end-maxFragLookUpTolerance] range. | | defaultAudioCodec | undefined| undefined | If audio codec is not signaled in variant manifest, or if only a stream manifest is provided, libraty tries to guess audio codec by parsing audio sampling rate in ADTS header. If sampling rate is less or equal than 22050 Hz, then libraty assumes it is HE-AAC, otherwise it assumes it is AAC-LC. This could result in bad guess, leading to audio decode error, ending up in media error. It is possible to hint default audiocodec to libraty by configuring this value as below: |

Player methods

The info below is the methods and properties of Player, you can controll the player or get some useful info;

static methods

|methods | result | Description | |-------------------------------|--------------------|-------------------------------------| |HJPlayer.isSupported() | boolean | whether the browser support this lib| |HJPlayer.typeSupported() | Object | return the media type of browser support | |HJPlayer.HJPlayerDefaultConfig | Object | the default config of player |

Instance methods

|methods | result | Description | |------------------------------|--------------------|-------------------------------------| | on() | void | bind callback for player events | | off() | void | cancel bind callback for player events| | attachMediaElement() | void | bind media element | | detachMediaElement() | void | remove the link of the media element with SourceBuffer | | load() | void | load the media stream | | unload() | void | unload the media stream | | play() | Promise | the player plays the video |
| pause() | void | the player pauses |

Instance property

|property | result | Description | |------------------------------|--------------------|-------------------------------------| | type | string | player type: 'MSEPlayer' or 'NativePlayer'| | buffered | TimeRanges | the TimeRanges of the player | | duration | number | the duration of the media element | | volume | number | the volume of the video | | currentTime | currentTime | the currentTime of the video | | muted | boolean | whether the video is muted | | mediaInfo | Object | the meida info (metadata) | | statisticsInfo | Object | the statistics info of player stauts, such as dropframe, speed etc; |

HJPlayer.Events

HJPlayer.Events, you can use the way Player.on(HJPlayer.Events.xxx, fn) to get the info of player when play, Player.off(HJPlayer.Events.xxx) cancel listener

| Event | Description | | ------------------- | ---------------------------------------- | | ERROR | An error occurred by any cause during the playback | | LOADING_COMPLETE | The input MediaDataSource has been completely buffered to end | | RECOVERED_EARLY_EOF | An unexpected network EOF occurred during buffering but automatically recovered | | MEDIA_INFO | Provides technical information of the media like video/audio codec, bitrate, etc. | | METADATA_ARRIVED | Provides metadata which FLV file(stream) can contain with an "onMetaData" marker. | | SCRIPTDATA_ARRIVED | Provides scriptdata (OnCuePoint / OnTextData) which FLV file(stream) can contain. | | STATISTICS_INFO | Provides playback statistics information like dropped frames, current speed, etc. | | GET_SEI_INFO | it will returns the SEI info(Uint8Array) . | | HJ_PLAYER_LOG | it will returns a log contains a type: string and a info: string | | MANIFEST_PARSED | you can get the details of index.m3u8: Object |

HJPlayer.ErrorTypes

when player is playing, it maybe happen something unexpected, you can use player.on(HJPlayer.Events.ERROR, () => {}) to get what happend, HJPlayer.ErrorTypes.xxx is the error type; you will also get a Object contain reason, it will tell you more details

| Error | Description | | ------------- | ---------------------------------------- | | NETWORK_ERROR | Errors related to the network | | MEDIA_ERROR | Errors related to the media (format error, decode issue, etc) | | OTHER_ERROR | Any other unspecified error |

HJPlayer.ErrorDetails

prefix with HJPlayer.ErrorDetails: HJPlayer.ErrorDetails.xxxx

| Error | Description | | ------------------------------- | ---------------------------------------- | | NETWORK_EXCEPTION | Related to any other issues with the network; contains a reason | | NETWORK_STATUS_CODE_INVALID | Related to an invalid HTTP status code, such as 403, 404, etc. | | NETWORK_TIMEOUT | Related to timeout request issues | | NETWORK_UNRECOVERABLE_EARLY_EOF | Related to unexpected network EOF which cannot be recovered | | MEDIA_MSE_ERROR | Related to MediaSource's error such as decode issue | | MEDIA_FORMAT_ERROR | Related to any invalid parameters in the media stream | | MEDIA_FORMAT_UNSUPPORTED | The input MediaDataSource format is not supported by flv.js | | MEDIA_CODEC_UNSUPPORTED | The media stream contains video/audio codec which is not supported |

Licence

HJPlayer.js is released under Apache 2.0 License

super class

This player is extended flv.js and hls.js

How it works?