MinimServer

Home

Features

MinimServer 2.2

License options

Downloads

Release notes

Quick start

MinimWatch

User guide

Support

Troubleshooting

Forum

MinimStreamer

License terms

UPnP and DLNA

Technology

Contact

Latest news

(2024/04/14) Configuration status web page updated automatically

Latest change

(2024/07/15) MinimServer 2.2 update 253 has been released

Scripting and Web API

Table of contents

Command scripting
Batch mode and interactive mode
Some examples
Command output
Web API

Command scripting

From version 0.8.4 onwards, MinimServer and MinimWatch include a scripting client application. You can use this application to control and configure MinimServer by running a single MinimServer console command or a scripted list of console commands (a command script). The available commands are listed in the Controlling MinimServer using console commands section.

The scripting client application must be run in a command prompt window (Windows) or a terminal window (Mac or Linux). The command to run the scripting client application is named mscript and its location depends on which platform you are using, as follows:

The syntax of the mscript command is as follows:
 mscript [ options ] [ script-file ]

where options is any combination of the following:

-i   use interactive mode
-a address   host and port address of the server
-t timeout   number of seconds (default 5) to wait for server response
-c command   single command to run
-d   enable debug output
--help   show syntax summary

If you specify the script-file argument, mscript reads the command script from a file, which must be plain text. if you don't specify the script-file argument, mscript reads the command script from the standard input stream, which can either be connected to an interactive console or redirected to read input from a pipe or a file. If the -c option is specified, the value of this option is used as a single command to run instead of running a command script.

If the mscript command is invoked with no options or arguments and the standard input stream isn't redirected, mscript displays a syntax summary. If you want to read commands from an interactive console with defaults for all options, you can use the command mscript -i to do this.

The host and port address of the server can be an IP address (for example, 192.168.1.20) or an IP address and port number (for example, 192.168.1.20:9792). If this address isn't specified, the mscript command attempts to locate a MinimServer instance running on the local machine and run the command script on this instance.

A command script can contain any number of commands. Lines starting with '#' are ignored. If the script contains multiple commands, the commands must be separated by newline characters.

Batch mode and interactive mode

The mscript command can run in either batch mode or interactive mode. The -i option is used to specify interactive mode. If this option isn't specified, the default setting is interactive mode if mscript is reading commands from an interactive console and batch mode in all other cases.

In batch mode, mscript sends a list of commands (a command script) to MinimServer and MinimServer runs these commands in sequential order until the end of the script is reached or a command returns an error. If a command returns an error, no more commands are run. The output from the last command to be run (either sucessfully or with an error) is written by mscript to the standard output stream in the format described in the Command output section below. Batch mode is useful for running a fixed sequence of commands.

In interactive mode, mscript reads commands one at a time and sends them to MinimServer for immediate processing. When a command completes (successfully or with an error), mscript writes the command output (see the Command output section below) to the standard output stream before reading the next command. Command processing ends when mscript reads a null command (empty string) or reaches the end of the command script. Interactive mode is useful if mscript is reading commands from an interactive console or being controlled programmatically by another application.

The Linux download packages for MinimServer and MinimWatch include a demonstration shell script scriptdemo.sh that shows how the interactive mode of mscript can enable an application to control MinimServer by issuing commands and using programmatic logic to read command output and determine what action to take next.

Some examples

Here are some examples of how the mscript command can be used:

mscript myscript.txt 
reads a command script from a file named myscript.txt and runs the commands in batch mode on a MinimServer instance running on the local machine
mscript -i 
reads commands from an interactive console and runs the commands in interactive mode on a MinimServer instance running on the local machine
mscript -c rescan 
runs the single command rescan
myprog | mscript 
runs the program myprog to output a command script that is piped to the mscript command and run in batch mode by a MinimServer instance on the local machine
myprog | mscript -i 
runs the program myprog to output a command script that is piped to the mscript command and run in interactive mode by a MinimServer instance on the local machine
mscript <infile >outfile  
reads the command script from the file infile, runs the command script in batch mode and writes the command output to the file outfile
mscript -a 192.168.1.20 myscript.txt 
reads a command script from a file named myscript.txt and runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20
mscript -a 192.168.1.20:9792 myscript 
reads a command script from a file named myscript and runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20 and HTTP port number 9792

Command output

mscript writes the output from running the command script (in batch mode) or each individual command (in interactive mode) to the standard output stream. This output is in three parts:

For example, the command about might produce the following output:
 +*about
 MinimServer
0.8.4, Copyright (c) 2012-2017 Simon Nash. All rights reserved.
 +:status=0

and the command install foo might produce the following output:
 +*install
foo
 Download
resource not found: foo.jmpkg
 +:status=1

For successful completion of a command or command script, the completion status is 0. If the command or command script has been run by MinimServer and returned a error, the completion status is 1. If the command or command script couldn't be sent to MinimServer, mscript writes an error message to the standard error stream and the completion status is 2 if the server address wasn't found or 3 for any other error.

The following commands are treated specially:

restart restarts the server and waits for the server to restart. If any commands follow this command in the script, the next command is run when the server has restarted.
rescan performs a server rescan (including a server restart). If mscript is running in batch mode and there are any commands following this command in the script, the next command is run when the rescan has completed. If mscript is running in interactive mode and there are any commands following this command in the script, the next command is run when the server has restarted and is beginning the rescan.
relaunch  relaunches the server and waits for the server to relaunch. If any commands follow this command in the script, the next command is run when the server has relaunched.
exit terminates the server. If any commands follow this command in the script, an error is returned for the next command.

Web API

The MinimServer web API provices a mechanism for applications to send commands programmatically to MinimServer. An example of an application that does this is the mscript scripting client application (see the Command scripting section).

The web API uses the standard HTTP protocol. An application that needs to control MinimServer using the web API must send an HTTP POST request to the URL
 http://address:port/
where address is the IP address of the machine runing MinimServer and port is the HTTP server port that MinimServer is using on this machine (see the HTTP server port section). The content type for the request must be text/plain and the content data must be a command script containing console commands listed in the Controlling MinimServer using console commands section.

The command script can contain any number of commands. Lines starting with '#' are ignored. If the script contains multiple commands, the commands must be separated by newline characters.

MinimServer runs each command in the script in sequence until all commands have completed successfully or any of the commands returns an error. If a command returns an error, no more commands are run.

The HTTP POST response content data has a content type of text/plain and contains the last command that was run and the output from this command, preceded by the prefix +*. For example, the command about might return the following:
 +*about
 MinimServer
0.8.4, Copyright (c) 2012-2017 Simon Nash. All rights reserved.

and the command install foo might return the following:
 +*install
foo
 Download
resource not found: foo.jmpkg

If all commands complete successfully, the HTTP POST response status code is 200. If an error occurs while running a command, the HTTP POST response status code is 400 or greater.

The following commands are treated specially:

restart restarts the server and waits for the server to restart. The HTTP 200 OK response is sent when the server has restarted. If any commands follow this command in the list, the next command is run when the server has restarted.
rescan performs a server rescan (including a server restart). The HTTP 200 OK response is sent when the server has restarted and is beginning the rescan. If any commands follow this command in the list, the next command is run when the rescan has completed.
relaunch  relaunches the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the next command.
exit terminates the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the next command.