migrationguide.md

Migration Guide for Version 2

If you've been using Version 1 of Node-MPV here's how you can migrate your app to Version 2. A lot has changed and there is quite a lot of changes you will have to make to your code, but it really works so much better.

• Migration Guide for Version 2
  • Starting MPV
  • Promisified Methods
    • Using Async/Await
    • Chaining Promises
  • Statuschange event
  • Observing properties
  • Changed Methods - mute
    • loop
    • loopPaylist & clearLoopPlaylist
  • Error Handling with the new Error Object

Starting MPV

In Version 1 you didn't need to explicitly have to start the player, in Version 2 you do.

// Version 1 Code
const mpvAPI = require('node-mpv');
const mpv = new mpvAPI();

// player is running

This didn't check at all if everything worked out, like binding the IPC socket or if the provided mpv binary actually existed.

// Version 2 Code 
const mpvAPI = require('node-mpv');
const mpv = new mpvAPI();
// player is NOT running yet

mpv.start()
.then(() => {
    // player is running
})
.catch((error) => {
   // catches any error that might've happend while starting the player
})

Promisified Methods

In Version 1 Node-MPV just sent commands to the player but didn't check if they actually worked. This has change with Version 2 but with this they way you should use the methods has changed as well.

// Version 1 Code
mpv.load('your/favourite/song.mp3', 'replace');

This does not check if that file actually exists, could be loaded or if replace was actually a valid option.

From within an async function, Use the then() and catch() synthax if not

// Version 2 Code
try{
	await mpv.load('your/favourite/song.mp3', 'replace')
}
catch(error) {
	// catches any errors
});

With this you can both be sure that the file is being played when you're executing your next function calls and any error is caught, for example if the file was not found or could not be played or even if replace was not a valid option.

Using Async/Await

Since Node 8.0.0 Async/Await is fully supported. The code from above can be shortend a lot if run from within an async function.

const someAsyncFunction = async () => {
	try{	
		await mpv.start();
		await mpv.load('your/favourite/video.mkv');
		// video is running
		console.log(await mpv.getDuration());
		await mpv.mute();
	}
	catch (error) {
		console.log(error);
	}
}

Chaining Promises

If (for some reason) you don't want to or cannot use async / await you can chain promises like seen in the following code

mpv.start()
.then(() => {
	return mpv.load('your/favourite/video.mkv');
})
.then(() => {
	// video is running
	return mpv.getDuration();
})
.then((duration) => {
	// outputs the video duration
	console.log(duration);
	return mpv.mute();
})
.then(() => {
	// video is muted
})
.catch((error) => {
	// any error from any of the calls above will be caught here
});

Statuschange event

The statuschange event has been renamed to status and fires individually for every observed propertey. The object looks like the following

{
	'property': <name of the property>,
	'value': <value of the property>
}

Observing properties

In version one you had to manage some ids if you wanted to observe and later unobserve some properties. Luckly, with Node-MPV 2 this handled internally. All you have to do, is name which property you want to have observed.

// Version 1 Code
mpv.observeProperty('display-fps', 15);
mpv.unobserveProperty(15);

// Version 2 Code
await mpv.observeProperty('display-fps');
await mpv.unobserveProperty('display-fps');

Changed Methods

Some methods were changed in the way they are used or called

mute

The methods mute(), unmute() and toggleMute() are now one single method called mute() that can take an argument. The code below shows the Version 1 style together with the Version 2 counterparts

// Version 1 Code
mpv.mute();
mpv.unmute();
mpv.toggleMute();
// Version 2 Code
await mpv.mute(true);
await mpv.mute(false);
await mpv.mute();

loop

Loop can be used exactly how it was used in Version 1 without causing any problems. However, the method can also be used without passing a parameter now, which will toggle the mute state between on and off

loopPaylist & clearLoopPlaylist

The two methods loopPlaylist() and clearLoopPlaylist() are now one method loopPlaylist, which works exactly as the new loop() method, described in the paragraph before.

Error Handling with the new Error Object

With Version 2, I introduced an error object, to help you out if something didn't work. You can read more about it here (Just click on the Error Handling section in the table of contents). Make sure to make use of it, as it is pretty helpful.