JTVLANServer exposes a simple API through HTTP calls. Using this API it is possible to write alternative clients to JTVLANServer.

Version 0.2.0 of the server API is an extension of the 0.1.4 version. Software written to work with the 0.1.4 version should work with the 0.2.0 version without modifications. The extensions are related to some additional data returned by the server status call, and to a new call which estabilishes a persistent connection from which clients are able to receive real time events from the server.

The API is exposed through the following single WebScheduler servlet:

/servlet/JTVLANServerRes

different server tasks can be requested by passing suitable request parameter which are documented in the following sections.

Each call returns the response in plain text format. The first line of the response is always a number indicating the return code of the call. A value of 0 (zero) indicates successful processing of the request. A non-zero value indicates that an error occurred during the processing. The meaning of the error codes are detailed at the end of this page.

All the lines after the first one represent the body of the response, which contains optional return data returned by the server in response to the client. In case the request generated an error, the body may contain textual information about the error itself.

To get server version and configuration call the entry point url without any parameter:

/servlet/JTVLANServerRes

The requested data is returned in Java properties format. A sample response is as follows:

0
jtvlanserver.version: 0.1.3
vlc.params: -I rc --rc-quiet
capture.waitbeforestream: 5000
capture.maxwaitforcreate: 3000
capture.type: 2
capture.prefix: tmpcap_
path.tmpcapture: G:\Timeshifting
capture.timeformat: yyyyMMdd-HHmmss
vlc.sout: standard{access=http,mux=ts,url=:7777}
vlc.exepath: C:\Program Files\VideoLAN\VLC\vlc.exe
capture.ext: .ts
path.recordings: G:\Recordings

The following call requests a list of the channel names:

/servlet/JTVLANServerRes?action=listchannels

The requested list is returned as a single line of text. Channel names are separated by the ; (semicolon) character. Channel names are returned in alphabetic order. Here is a sample response containing three channels:

0
RaiDue;RaiTre;RaiUno;

To get a complete channel list containing detailed data for each channel you should call:

/servlet/JTVLANServerRes?action=listchannelsext

The channel list is returned in Java properties format as in the following sample:

0
channel.0.name: 24ore-tv
channel.0.apid: 660
channel.0.vpid: 513
channel.0.frequency: 650000
channel.0.bandwidth: 8
channel.0.programid: 22
channel.0.atype: MPG
channel.1.name: BBC World
channel.1.apid: 690
channel.1.vpid: 516
channel.1.frequency: 650000
channel.1.bandwidth: 8
channel.1.programid: 25
channel.1.atype: MPG
. . . .
. . . .

apid and vpid identify audio and video PID. If the PID is not available the value is set to -1.

To request JTVLANServer to play or record (on the server) a channel and to start streaming it you should call:

/servlet/JTVLANServerRes?action=play&channel=channelname&arate=audioBitrate&vrate=videoBitrate
/servlet/JTVLANServerRes?action=record&channel=channelname&arate=audioBitrate&vrate=videoBitrate

where channelname is the name of the requested channel. If the parameters arate and vrate are present (they are optional), the server will transcode the audio and video streams according to the requested bitrates.

This action does not return any data apart the result code.

To request JTVLANServer to stop any activity you should call:

/servlet/JTVLANServerRes?action=stop

This action does not return any data apart the result code.

To get a report of the current server activity you should call:

/servlet/JTVLANServerRes?action=status

The status information is returned in a Java properties file format. If the server is playng or recording this command returns the detailed information of the activity as in the following example:

0
status: 2
status_name: Playing
capid: 0
channel: RaiDue
channel_frequency: 818000
channel_apid: 651
channel_vpid: 513
channel_bandwidth: 8
channel_programid: 3402
channel_audiotype: MPG
started_millis: 1148251272089
started: 22/05/2006 00:41:12
length: 5258
length_min: 0 min 5 sec
capfile: G:\\\\Timeshifting\\\\tmpcap_RaiDue_20060522-004102.ts
capfilesize: 6
available_cards: 0
used_card_id: 0
next_schedule: No pending tasks

Possible status values-names are: 0-Stopped, 1-Starting, 2-Playing, 3-Stopping

length is the viewing time of the current channel in milliseconds.

capfilesize is the current size of the captured data expressed in Mb.

available_cards the number of capture cards still available to WebScheduler.

next_schedule the time in minutes to the next pending scheduled task.

To receive server events call:

/servlet/JTVLANServerRes?action=monitor

This call is different since the server never finishes sending data to the response but instead it uses the response stream to write events to be sent to the client. Events are single lines of text each one with the following syntax:

TIMESTAMP:EVENT

TIMESTAMP is the usual number of milliseconds since 1970, while EVENT is a string identifying the event. The following events are supported:

KeepAlive This event is constantly sent once every 10 seconds to avoid client disconnections due to timeouts

Stopped Server has stopped from a capture

Starting Server has received a request for starting a capture

Playing Server is playing and streaming

Stopping Server has received a request to stop a capture.

FreeCardRequest Server will start a scheduled capture withinn about 2 minutes and needs the user to stop watching TV and free the card to be able to perform the recording.

StreamNotReady Server has started the capture but was unable to start streaming because VLC generated errors reading the capture data.

The following table summarizes the meaning of the most commmon error codes: