Overview

What is jMythAPI?

jMythAPI is a java library to query and control a MythTV backend and MythTV database. It uses the Myth protocol to communicate with the MythTV backend and the MySQL JDBC driver to query the MythTV database. It provides a high level API enabling java developers to easily access MythTV, without the need to know all the details about the underlying protocol and differences between various protocol versions.

What is MythTV?

MythTV is a free and open source digital video recorder (DVR) for watching and recording television. It turns a computer into a powerfull home theater, supporting network streaming, digital video recording and provides additional plugins to watch and archive DVDs, listen to digital music collections, and many more.

The MythTV system is split into the following components:

  • MythTV Database
  • MythTV Backend Server(s)
  • MythTV Frontend(s)

The communication between the frontends and backends is done using the Myth protocol.

See www.mythtv.org to learn more about MythTV.

Features

The following things can be done with jMythAPI:

  • Query backend status
  • Read and write backend settings
  • Receive backend events
  • List channels, download channel icons
  • List programs data
  • List, add or remove recording schedules.
  • List, delete, download or stream recorded programs
  • Generate recording preview images
  • Watching Live TV
  • Query and set bookmarks
  • List, start, stop, pause or continue backend jobs
  • Control recorders, switch channels and recorder inputs

If jMythAPI does not fulfill all your requirements, take a look at other projects implementing the Myth protocol.

Requirements

Requirements to use jMythAPI:

  • Java JRE >= 1.5.0 (Download)
  • MySQL JDBC driver (Download)
    if you need to connect to the MythTV database

The library ostermiller-syntax, which is additionally listed in the Project Dependencies, is just used for code highlighting in JavaDoc.

Supported MythTV versions

The following MythTV versions are supported:

  • All MythTV versions released between 2004-01-29 and 2013-09-18
  • MythTV release versions: 0.14 - 0.27
  • MythTV protocol versions: 01 - 77

Depending on the MythTV protocol version that a backend is speaking, different protocol commands are supported and the required request- and received response-parameters may be different.
Please read the JavaDoc to see which features are available in which MythTV protocol version.
A changelog of all protocol version changes can be found here.

Documentation

The main documentation of jMythAPI is written in JavaDoc.
The JavaDoc API documents are available here.

Protocol version related infos

Beyond a typical JavaDoc documentation, the jMythAPI JavaDoc pages provide additional infos, which are important for developers:

  • Protocol version changelog: (Example)
    Which protocol versions are supported by jMythAPI, and which changes were done to a specific version in comparison to the predecessor version, can be seen in the JavaDoc of the Enumeration ProtocolVersion.
  • Protocol version range: (Example)
    In which protocol versions a protocol-command or a request- or response-parameter is supported, is shown via a protocol version range.
    The lower bound of the range specifies the version when an element was introduced, whereas the upper bound specifies the version when the element was removed.
  • Protocol version matrix: (Example)
    Many protocol response objects have multiple properties. To make it easier to get an overview, which properties are available in which protocol version, a version matrix is displayed.
  • Protocol commands: (Example)
    Although jMythAPI provides classes and functions to hide the protocol level details from the API user, all supported commands are documented.

Please read the Documentation for a more detailed description about the information types listed above.

Getting started

To get started with jMythAPI you should read the following JavaDoc pages:

  • Supported protocol versions:
    See here for all protocol versions supported by jMythAPI.
  • Supported protocol commands:
    See here for all protocol commands supported by jMythAPI.
  • Work with a MythTV backend:
    See here how to send commands to a MythTV backend.
  • Work with a MythTV recorder:
    See here how to control a MythTV recorder.
  • Work with a MythTV encoder:
    See here how to work with a MythTV encoder.

Usage Examples

Query pending recordings:

In the following example we connect to a MythTV-backend and fetch the list of pending recordings.

// create a backend object and connect to the backend
IBackend backend = BackendFactory.createBackend("mythbox");
backend.connect();
   
// register as a playback client
backend.annotatePlayback();
   
// query pending recordings
IRecordingsPending pendingRecordings = backend.queryAllPending();
for (IProgramInfo program : pendingRecordings) {
   // we are only interrested in recordings with "WILL_RECORD" status
   IProgramRecordingStatus recStatus = program.getRecordingStatus();
   if(!recStatus.hasStatus(IProgramRecordingStatus.Status.WILL_RECORD)) continue;
          
   // print out the found recodings
   System.out.println(String.format(
      "%1$tF %1$tT - %2$s (%3$s)",
      program.getStartDateTime(),
      program.getTitle(),
      program.getChannelSign()
   ));
}
   
// close backend connection
backend.close();

The above example will output, e.g.

 MythTV has 4 pending records
 2011-04-17 18:10:00 - Die Simpsons (PRO7)
 2011-04-17 20:15:00 - 10.000 BC (PRO7)
 2011-04-18 22:15:00 - Roter Drache (ZDF)
 2011-04-21 20:15:00 - Dr. House (ORF1)

More Examples:

See here for more usage examples.

License

jMythAPI is licensed under the GNU Library or "Lesser" Public License (LGPL).

Contact

Any questions? Contact Martin Thelian.