Getting Started

What is a package?

A package is quite simply a combination of a few files, in a zip file, ready to distribute to the greater public, or to install on your own Emby server.  It is a relatively new concept within Emby Scripter-X so please be patient with our knowledgebase and implementation changes - we're still working on maturing its core.

Packages are written in Javascript (currently ES5 and Partially ES6 compliant), however we are currently working on implementing NodeJS as one of our core scripting engines -- we're just waiting for the NodeJS engine to be compatible with Dotnet CoreCLR.


So, what's inside a package zip file?

PackageInfo.json - this file provides essential information about your package to the Emby Scripter-X Package Installer.

{ 
	"Id":"scripterx.package.example", 
    "Name": "Example Package", 
    "Description": "An example package for the ScripterX package system.", 
    "Author": "Anthony Musgrove", 
    "Email": "anthony@emby-scripterx.info",
  	"Version": "1.5.2",
}

Package.js - this is your main package script file.  It is currently where all your package's javascript code resides.

You can subscribe to various available events in your package by using the event ID, prefixed with an underscore.  As of 11th of June 2020, the events supported are:

_package_init()
_onAuthenticationFailed(context)
_onAuthenticationSuccess(context)
_onLibraryScanComplete(context)
_onMediaItemAdded(context)
_onMediaItemRemoved(context)
_onMediaItemUpdated(context)
_onMediaItemAddedComplete(context)
_onPlaybackStart(context)
_onPlaybackStopped(context)
_onPlaybackProgress(context)
_onScheduledTask(context)
_onSessionStarted(context)
_onSessionEnded(context)
_onCameraImageUploaded(context)
_onLiveTVRecordingStart(context)
_onLiveTVRecordingEnded(context)
_onScheduledTaskStart(context)
_onScheduledTaskEnded(context)
_onAttachLiveTV(live_tv_name, live_tv_url)
_onLibraryRefreshStart(library_name)
_onLibraryRefreshEnded(library_name)
_onUserConfigurationUpdated(context)
_onUserPasswordChanged(context)
_onUserCreated(context)
_onUserDeleted(context)
_onUserLockedOut(context)
_onRecordingTimerCreated(context)
_onRecordingTimerCancelled(context)

Other functionality will be added as we progress along with the Packages implementation.   You can read more about the above functions on their respective pages.

PackageConfig.xml

This is your package's configuration file.   You can manipulate this file in your javascript package by utilising the ScripterX.Config.Set and ScripterX.Config.Get functions; you can read more about these functions on their respective wiki pages. 

If you wish to specify default values for various configuration items in your package, you can package this file up in your ZIP file for distribution.  All values in this file are treated as string values, unless you specify the type to cast the value to when using the ScripterX.Config.Get function. The format as as follows:

<?xml version="1.0"?>
<PackageConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Settings>
    <Setting>
      <Id>settingId</Id>
      <Value>settingValue</Value>
    </Setting>
  </Settings>
</PackageConfiguration>

 

PackageConfig.html

This is your package's configuration interface file.  It can be used to modify and manipulate your PackageConfig.xml by displaying a web-based interface to your package.

The format of this file is HTML markup.  ScripterX utilises the 'name' attribute of the input shown on the screen to link it to a configuration value in your xml file.   For example, if I have the item settingId as shown in the XML example above, and I wanted to allow the user to modify this value, I would select an appropriate input type (or select) on my interface, and assign the input's name to 'settingId', and the value to %settingId% (this is interpreted from your configuration when the interface renders).

Now when my user opens the configuration interface for my package, the interface will display my input field and the value of the input field would automatically be retrieved from my package config (which is already loaded in memory).

If this were a textbox, it would look like this:

<input type="text" name="settingId" value="%settingId%">

As of 16th June 2020, the plugin currently only supports text-typed html inputs, however radio buttons, selects and dropdown boxes do work for saving out, they just aren't build yet to render the current values properly.  This is part of a TODO.