HeapVideo

class - package heapvlc

Plays video through libVLC, decoding frames into a dynamic heaps texture shown via `bitmap`.
Backed by native/vlc.c (built into `vlc.hdll` by native/build.ps1), which has to exist before use.

libVLC does its own decoding, so `play()` takes anything it supports (mp4, mkv, webm, etc.)
and also supports URL streaming.

Standalone `h2d.Object` - doesn't depend on any particular host engine's update convention,
just Heaps' own per-frame `sync()`, so `new heapvlc.HeapVideo(parent)` works in any Heaps scene.

Members

Variables

var bitmap(default, null):h2d.Bitmap

The `h2d.Bitmap` child that displays decoded video frames. Untextured until the first frame arrives.

var loop:Bool

When true, playback restarts from the beginning instead of stopping at `onEndReached`.

var onEndReached:Void->Void

Fires when playback reaches the end of the media - after a loop restart, or after `stop()` on a non-looping end.

var onFormatSetup:(width:Int, height:Int) -> Void

Fires once the decoder reports the video's pixel size and `bitmap`'s texture has been (re)created.

var onPlaying:Void->Void

Fires when libVLC's "playing" event is observed; see `LibVLC.take_playing`. Can fire again after a pause/resume.

var onError:Void->Void

Fires once when the native player reports a playback error; call `getLog()` for details.

var fitWidth:Null<Float>

When set, `bitmap` is scaled down (never up) to fit within this size and centered on
whichever axes are set, once the native dimensions are known. Set before or after play().

var fitHeight:Null<Float>

var playing(get, never):Bool

Whether the native player considers itself currently playing. `false` when nothing is loaded.

var duration(get, never):Float

Media duration in milliseconds, or `0` when nothing is loaded.

var position(get, set):Float

Playback position, normalized `0..1`. Writable to seek; `0` when nothing is loaded.

var time(get, set):Float

Playback position in milliseconds. Writable to seek; `0` when nothing is loaded.

var volume(get, set):Int

Volume, `0..100+` (`100` = normal). Defaults to `100` when nothing is loaded.

var muted(default, set):Bool

Whether audio output is muted.

var rate(get, set):Float

Playback speed multiplier, e.g. `0.5` for half speed, `2.0` for double. `1.0` when nothing is loaded.

var audioTrackCount(get, never):Int

Number of available audio tracks, or `0` when nothing is loaded.

var audioTrack(get, set):Int

Selected audio track id (not necessarily 0-based - see `audioTrackCount`), or `-1` for none.

var subtitleTrackCount(get, never):Int

Number of available subtitle tracks, or `0` when nothing is loaded.

var subtitleTrack(get, set):Int

Selected subtitle track id (not necessarily 0-based - see `subtitleTrackCount`), or `-1` for none/disabled.

Functions

function new(?parent:h2d.Object):Void

public function new(?parent:h2d.Object) {
		super(parent);
		bitmap = new h2d.Bitmap(this);
		ensureInit();
	}

Creates the player and its `bitmap`, optionally attaching it under `parent`. Runs one-time
libVLC init if needed.

?parent

h2d.Object

Optional Heaps object to attach this player under.

function load(path:String, ?isUrl:Bool):HeapVideo

public function load(path:String, ?isUrl:Bool):HeapVideo {
		stop();
		var url = isUrl != null ? isUrl : urlScheme.match(path);
		handle = LibVLC.open(toCString(path), url);
		if (handle == null)
			throw 'HeapVideo: failed to open "$path"' + errorSuffix();
		return this;
	}

Stops any current playback and opens `path` (a local file path or a streaming URL) for
this player, without starting playback.

path	String	A local file path or a streaming URL.
?isUrl	Bool	Whether `path` is a URL. Auto-detected from a `scheme://` prefix when omitted.

Returns: This player, for chaining.

Throws: String if libVLC fails to open the source.

function play(?path:String, ?isUrl:Bool):HeapVideo

public function play(?path:String, ?isUrl:Bool):HeapVideo {
		if (path != null) load(path, isUrl);
		if (handle == null)
			throw "HeapVideo: play() called with nothing loaded - call load() or pass a path";
		errorSeen = false; // vlc_play() resets the native errored flag along with starting playback
		if (!LibVLC.play(handle))
			throw "HeapVideo: failed to play" + errorSuffix();
		return this;
	}

Starts playback. Pass `path` to `load()` it first, or call after a previous `load()`.

?path	String	Optional media to `load()` before playing.
?isUrl	Bool	Forwarded to `load()` when `path` is given.

Returns: This player, for chaining.

Throws: String if nothing is loaded or if libVLC fails to start playback.

function getLog():String

public function getLog():String {
		var buf = haxe.io.Bytes.alloc(8192);
		var len = LibVLC.get_log(buf, buf.length);
		return buf.getString(0, len);
	}

Recent libVLC diagnostic log (info/warning/error) since this player's last `load()`/
`play()` call - useful when playback silently doesn't progress (wrong URL, unresolved
stream, missing codec, ...) without `open()`/`play()` themselves reporting failure.

Returns: The diagnostic log text, or `""` if there's nothing logged.

function pause():Void

public function pause():Void {
		if (handle != null) LibVLC.set_pause(handle, true);
	}

Pauses playback. No-op when nothing is loaded.

function resume():Void

public function resume():Void {
		if (handle != null) LibVLC.set_pause(handle, false);
	}

Resumes playback after `pause()`. No-op when nothing is loaded.

function stop():Void

public function stop():Void {
		if (handle != null) {
			LibVLC.close(handle);
			handle = null;
		}
		sizeKnown = false;
		frameWidth = 0;
		frameHeight = 0;
		errorSeen = false;
	}

stops playback and frees the native player. safe to call when nothing's playing.

function destroy():Void

// destroys the object.
	public function destroy():Void {
		stop();
		remove();
	}