Jessibuca Setup Guide: H5 Player Configuration, Decoding Modes, and Troubleshooting

Jessibuca is an open-source, pure HTML5 live stream player. By using Emscripten, it compiles audio and video decoding libraries into WebAssembly (WASM), allowing them to run directly within the browser. It is compatible with almost any modern environment—including desktop browsers, mobile devices, and WeChat—without requiring additional plugins or extensions.

Recommended Base Configuration

Protocol Handling

• HTTP Environment

  {
      useMSE: true,
      autoWasm: true
  }
  

• HTTPS Environment

  {
      useWCS: true,
      autoWasm: true
  }
  

Framework Integration

Vue

Assign the Jessibuca instance directly to the this context. Avoid placing the instance inside the data object to prevent Vue's reactivity system from tracking the player’s internal state, which can cause performance issues. If you must store it in data, prefix the property name with _ or $. You can then access it via this.$data._property.

Alternative approaches:

• Vue Prototype: Vue.prototype.$player = new Jessibuca({})
• $options: this.$options.jessibuca = new Jessibuca({})

React

Attach the instance directly to the class context (this). Storing the player instance in the component state is not recommended.

Installation and Dependencies

Why Standard npm Installation May Fail

Because the project relies on WASM, standard package managers like npm or yarn often struggle to resolve binary dependencies correctly within the node_modules directory. Consequently, a standard installation may not work out of the box.

Workarounds

• Base64 Bundling: Compile the WASM file into a base64 string and bundle it directly within the JavaScript file. Note that this significantly increases the file size; use this method only if the added weight is acceptable for your project.
• Vue CLI Plugin: Use the vue-cli-plugin-jessibuca for easier integration:
  • Install: npm install vue-cli-plugin-jessibuca -D
  • Usage: The plugin automatically injects the necessary script tags into your HTML. You can then access the player via window.Jessibuca. Example: const instance = new window.Jessibuca({}).

Decoding Methods

Hardware Decoding

Both useMSE and useWCS utilize hardware acceleration. Their capabilities differ as follows:

Software Decoding (WASM)

• Supports H.264 and H.265 at standard resolutions. The Pro version is required for high-resolution and high-frame-rate streams.
• Compatible with both HTTP and HTTPS.
• Automatically activates as a fallback if hardware decoding fails.

Priority Order

The player follows this hierarchy: useMSE > useWCS > WASM.

Protocol Support

Browsers do not natively support rtsp:// or rtmp:// streams. Jessibuca works with http(s)://, ws(s)://, WebRTC, and WebTransport.

Solution

To play unsupported streams, route them through a media server like Monibuca (M7S).

• Download: m7s.live/download
• Official Site: m7s.live

File Placement and Loading

Custom Directory

Place jessibuca.js, decoder.js, and decoder.wasm in a dedicated subfolder (e.g., /jessibuca).

• Include in HTML: <script src="./jessibuca/jessibuca.js"></script>
• Instance Configuration:

  {
      decoder: '/jessibuca/decoder.js'
  }
  

CDN Setup

To use a CDN, edit decoder.js and change wasmBinaryFile to an absolute URL: wasmBinaryFile='https://cdn.com/decoder.wasm'. Afterward, rebuild the project with npm run build. Pro version users can modify the WASM CDN path directly within rollup.config.js.

Rendering Differences

• WASM Software Decoding: Defaults to <canvas> rendering. The Pro version allows the use of the <video> tag.
• MSE Hardware Decoding: Defaults to the <video> tag. The Pro version supports <canvas>.
• WebCodecs (WCS) Hardware Decoding: Defaults to <canvas>, but also works with the <video> tag. The Pro version supports canvas webgl2.

WebGL Conflicts

If a page uses heavy WebGL resources (such as 3D backgrounds or interactive maps), the player may crash, often indicated by a "sad face" icon. To fix this:

• Switch the player to <video> tag rendering.
• Reduce the WebGL load from other elements on the page.

Multi-Stream Playback

Software decoding multiple streams simultaneously puts a heavy load on the CPU, which can lead to lag and stuttering. Use hardware decoding whenever possible. If hardware decoding is unavailable, limit the number of simultaneous streams.

Additionally, browsers limit concurrent HTTP/1.x connections to the same origin (Chrome caps this at 6). Workarounds include:

• Using WebSockets (e.g., WS-FLV).
• Enabling HTTP/2 on your server.
• Distributing streams across multiple subdomains to bypass the per-domain connection limit.

Latency

• Open-Source Edition: The WASM decoder drops frames to maintain real-time playback, but MSE and WCS do not. Latency may increase if the browser tab runs in the background.
• Pro Edition: Includes frame-dropping logic for WASM, MSE, and WCS, ensuring stable latency even when tabs are minimized or in the background.

Network issues, such as insufficient server upload bandwidth or excessively high bitrates, can also cause latency buildup. In these cases, optimize the network path or lower the stream bitrate.

Common Errors and Fixes

WASM 404 (IIS)

If your server is running IIS, you must manually add a MIME type for .wasm files: application/wasm.

Incorrect MIME Type

Ensure the server explicitly sends Content-Type: application/wasm for .wasm files. For Nginx, add the following to your configuration:

types {
    application/wasm wasm;
}

CORS Issues

The browser's same-origin policy may block cross-origin requests. Enable CORS on your media server. Example for a Node.js environment:

app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.header('Access-Control-Allow-Headers', 'Content-Type');
    next();
});

Black Screen with Active Data Flow

If the player shows a black screen despite receiving data, check the stream URL. The player uses the file extension (e.g., .flv) to determine the protocol. If your URL lacks an extension, force FLV parsing by setting isFlv: true in the configuration.

Green Screen or Corrupted Video

This usually occurs if the stream uses a pixel format other than YUV420P or if the video width is not a multiple of 8. In the Pro version, rendering via the <video> tag typically bypasses these hardware alignment issues.