Certain URLs are used to control the player and the playlist. Since when controlling the player the "result" is not actually a new page in the browser, but simply the fact that the player "did something", there are generally two variants for the control.

Simple URLs with appropriate parameters. Nemp will perform the appropriate action and then redirect the user to the player or playlist page, where the changes should be visible.

Requests from JavaScript. Nemp will perform the appropriate action, and return a suitable response that can be processed by the JavaScript. In some cases, it may be useful to replace a graphic, or to reload parts of the currently displayed web page.

Simple URLs

The variant with normal URLs is needed if no JavaScript is available. Nemp provides the "No JavaScript" theme for this purpose, but it should actually no longer be used.

Controlling the player with /playercontrol

To control the player, the /playercontrol page is called with an action parameter. Possible values for this are:

  • playpause: Continue or stop playback, depending on the current state of the player.
  • stop: Stopping the playback.
  • next: Play the next title.
  • previous: depending on the progress in the current title: play the current title again or play the previous title.

Example: /playercontrol?action=playpause 

Calling /playercontrol will redirect to the player page, i.e. it will be reloaded if necessary.

Controlling the playlist with /playlistcontrol

To control the playlist, the /playlistcontrol page is called with two parameters id and action. The value for id is the internal ID of the title in the playlist or media library. For the action parameter the following values are possible:

  • file_playnow: Starts playback of this title. If the title is not already in the playlist, it will be inserted after the currently playing title.
  • file_vote: Adds a "like" to the title and changes the position of the title in the playlist accordingly. If the title is not already in the playlist, it will be added to the playlist with one "Like".
  • file_add: Adds the title to the end of the playlist.
  • file_addnext: Adds the title behind the current title in the playlist
  • file_movedown: Moves the title one position up in the playlist
  • file_moveup: Moves the title one position down in the playlist
  • file_delete: Removes the title from the playlist.

Example: http://localhost/playlistcontrol?id=12345&action=file_vote Adds a "like" to the file with ID 12345.

When /playlistcontrol is called, it redirects to the playlist page, i.e. it is reloaded if necessary.

If more than one person has access to the web server, then it is recommended to prevent direct manipulation of the playlist. In the options this is controlled by the setting "Allow remote control of the player". Inserting files and prioritized playback via "Like" are safer in such a scenario.

However, the "admin" has full access to the player via the web browser regardless of the setting - unless the selected theme does not deliver the control buttons to the browser.

Usage of JavaScript

To control the player, it is not really necessary to reload the whole page in the browser afterwards. Therefore, there are other URLs that can be called by a JavaScript to control the player and/or reload parts.

Query player properties with /playerJS

For regular updates of the current title, /playerJS can be used. Optional parameter is data, which can have the values progress or volume. 

  • If the parameter data is not set, the content of the player page is returned as defined in the template PagePlayer.tpl. The JavaScript should replace the existing part with the received response.
  • progress allows to query the progress in the current title in percent. The response simply contains a string with the current progress (i.e. "0" to "100"), which the JavaScript can use to update the progress bar.
  • volume returns the current volume as a value between 0 and 100.

Example: http://localhost/playerJS?data=progress returns the percentage progress in the current track.

Controlling the player with /playercontrolJS

  • The actions playpause, stop, next and previous work in the same way as /playercontrol. Instead of redirecting to the player page, the player data is returned as output by /playerJS. The data parameter should be omitted here.
  • setprogress allows to scroll through the current title. A reasonable input method here is <input type="range">. Specify the progress in percent via the additional parameter value.
    The content of the response can be controlled via the additional parameter data=progress (see section /playerJS). 
    Example: playercontrolJS?action=setprogress&value=50&data=progress sets the progress to 50% and returns the value "50" as response if successful.
  • setvolume allows to set the volume of the player. As with setprogress, values between 0 and 100 are accepted. Additionally the values "1000" and "-1000" are allowed, which increases or decreases the volume by a fixed value.
    The content of the response can be controlled by the additional parameter data=volume (see section /playerJS). 

If control of the player via the browser is not allowed, then corresponding attempts will be answered with an appropriate HTTP StatusCode (e.g. 403 or 404). Normally this should not occur, because the web server does not insert the control buttons into the HTML code. At most, if the access rights are further restricted during operation, and a user has been shown an outdated player page with higher rights, this can happen. And of course, if an experienced user enters the corresponding URLs manually.

Loading the playlist with /playlistJS

When making changes to the playlist, it is also possible to query only the list of titles, i.e. the part that is inserted in the PagePlaylist.tpl template for the {{PlaylistItems}} placeholder. 

Previously, it was also possible to specify a parameter here that would only be used to reload individual titles. However, since this turned out to be not very useful, this option was removed in version 5.1.

Controlling the playlist with /playlistcontrolJS

For changing the playlist, i.e. inserting or deleting tracks, changing the order or voting, /playlistcontrolJS can be used. The parameters id and action work quite analogous to /playlistcontrol. Instead of a redirect to the playlist page, however, there is only a short response informing about the success or failure of the action.

  • file_playnow (immediate playback of a track)
    • "0": An error has occurred. Usually the transmitted ID is no longer valid, e.g. because the title has been deleted from the playlist otherwise in the meantime.
    • "<newID>": If successful, the ID of the newly started title is transmitted. 
  • file_add, file_addnext (insert a title into the playlist)
    • "ok": The title was successfully inserted into the playlist
    • "error": An error has occurred.
  • file_moveup, file_movedown (move a title in the playlist)
    • "ok": The title was moved successfully
    • "prebook": The title was only moved within the prebook list (see below)
    • "denied": The title could not be moved (e.g. the first title in the list cannot be moved further up)
    • "error": An error has occurred.
  • file_vote (voting a title)
    • "ok": The "like" was successfully registered and the title was re-sorted in the playlist according to the overall rating
    • "already voted": The user has already voted for this title. The "like" was not taken into account.
    • "spam": The user has liked too many titles recently. The "like" was not taken into account.
    • "error": An error has occurred.
  • file_delete (remove a title from the playlist)
    • "ok": The title was successfully removed from the playlist
    • "prebook": The title was only removed from the prebook list. However, it is still present in the playlist.
    • "error": An error has occurred.

If the triggering buttons are on the playlist page, the playlist should be reloaded with /playlistJS in any case. Individual changes in the HTML DOM are only of limited use, since the playlist may have changed elsewhere. So that the user is regularly shown a current playlist in the browser, it should be completely reloaded after changes by the user in case of doubt.

If the buttons for "Add" or "Like" are used outside the playlist page, then it is sufficient to replace the respective button with another element that shows the user that the click was successful (or not).

What is the "prebook list"? - The so called prebook list is a hidden feature of the Nemp playlist. You can set a temporary individual order in the player using the number keys 0..9. Just mark the track you want to listen to next and press 1. Mark another one with 2 and so on. If you want to change the order, it works the same way. If you want to remove a marker, press 0. A timer icon will then appear in the playlist with the playing order indicated behind it.

Using the prebook list in combination with the web server makes little sense and should be avoided. When "voting" the play order is achieved by reordering the tracks, with the prebook list this is intentionally not the case. These two approaches are not compatible and in combination cause unexpected behavior. Nevertheless, these cases are taken into account in the web server.