main install faq rio redrat sdk

JReceiver: SDK Documentation

JReceiver is a servlet-based audio server which features tightly integrated metadata indexing capabilities, browser-based management, an XML-RPC interface and support for network-based MP3 players like the Rio Receiver from Sonic Blue.

Introduction

This documentation is geared towards the software developer interested in using the JRec Server to interactively deliver audio to a hardware or software player. Also supported would be non-player clients, such as one that burns CDs from JRec's playlists or an mp3 uploader for portable players. See here for more ideas.

See http://jreceiver.sourceforge.net for a complete rundown of JRec's available features and other project details.

What's New

0.2.5 Alpha
16-May-2003
This release sees many bugfixes in both Ptarmigan and JReceiver.
Functionally the XML-RPC interface should be identical to that in the previous release.
0.2.4 Alpha
05-October-2002
Ptarmigan Media Parser for XML (http://ptarmigan.sourceforge.net) has replaced the existing metadata parsers with a new unified means of extracting metadata from files and streams.
Mime-type handling has been simplified. There is no longer a MimeRec object. They are passed through the API as simple strings ("audio/x-mpeg", e.g.).
Security has also been simplified with a simple true/false authorization on handler.methods replacing the needlessly obtuse 'authorization mask'.
There are two different kind of URLs in each source: 'Direct' and 'Content'. The former points to the original source, such as a "file:/" for a local file or "http://" for a remote stream. The latter points to the JReceiver Content Server for native or transcoded sources.
Note that in the one of the next few releases the API will likely be switching from key-based to cursor-based retrieval.
27-July-02 - Alpha Release 0.2.3

This is largely a maintenance release to fix some bugs that got past my testing for 0.2.2.
Some SDK changes: I've formalized the TuneQuery (TQ) interface. TuneQuery is now a bean with synchronized methods. In the future TQ will likely be expanded to support OR, NOT and AND expressions via nesting.
Furthermore, TQ will be be the basis of a new playlist type that will be similar to the present "Dynamic" playlists, but with the benefit of being database independent -- i.e., you can use them with MySQL, Postgres, etc.
There's also a new non-blocking OutputStream writer: jreceiver.util.ExpiringWriter(). It's used by the content engine and Rio driver to gracefully recover from blocking clients.
The "codec" parameter of TagEncoder.encodeTag() is now dynamic and accounts for transcoded sources. For example, both native MP3 and transcoded OGG->MP3 will have a "mp3" codec. Driver_id is now a parameter for encoding formatted tags.
22-July-02 - Alpha Release 0.2.2

Security marks the big change with this release. Client drivers/players must now provide a user_id/password to the RpcFactory prior to contacting the server. In addition, you can provide a set of credentials that the server must use in callbacks to your driver/player.
Note that the security uses Role-based Authorization where the user_id your player/driver uses is assigned a role (e.g., 'players') which in turn determines which methods of the JRec API may be invoked. This is all configurable from the Struts-based Manager.
Each Content URLs now has a alphanumeric random string embedded within it (e.g., "http://myserver.com/jreceiver/LJjw98wlw/Fly%20Me%20To%20The%20Moon.mp3") This limits access to content but should be transparent to driver/players.
The Settings framework has been upgraded. Not only does it allow for easy one-module configuration (see RioSettingCache.java for an example) but it caches your settings client-side, provides synchronized access, resets the cache as necessary AND protects your stored settings from those of other applications.
A new Menus interface has finally be added. TuneQuery objects are used to abstractly build a compound query that can be used to produce menus of Artists, Albums, Genres or Tune Titles. Once your user has selected what the tunes to play, you can feed that same TuneQuery object to Tunes.getKeysForQuery() to get the tune src_ids you need for play.
And finally, DeviceStatus has had its getSrcId() replaced with a more generic getSource() which means that player/driver clients that are playing from non-JRec sources can still provide metadata to JRec for display on the status panel.
I've updated the Java Developer Guide for JRec. See sdk-java-guide to get you started writing a client player or device driver.
27-May-02 - Alpha Release 0.2.0

JRec Alpha 0.2.0 released, featuring a new control architecture, permitting direct control via XML-RPC callback or indirect control via trainable IR emitters such as the RedRat2.
The JRec API has changed, again. The server architecture underwent a major refactoring over the past few months to consolidate redundant functionality and strive for consistency in the API. This will pave the way for upcoming features, such as security.

Overview

JReceiver is built on a conventional N-tiered architecture, its engine interacting with media players and the manager webapp via a network protocol, presently using XML-RPC over http.

Below is a diagram giving an overview of JRec's architecture. Parts of it will be explained in the remainder of this document as they relate to building client players and drivers.

JRec Architecture

JRec Server

The server offers three basic services: menus, metadata and media.

The engine maintains a rich database of metadata derived from the ID3 tags of a user's mp3 collection. Periodically, the scanner daemon is activated to scan the folders of the user's filesystem for new music. In addition, the user can define sophisticated playlists which are also maintained to this datastore.

Clients can access this datastore using the JRec API, available through and XML-RPC interface, for use in creating menus for the user to navigate, for details of a song to display to the user on its front panel or status window, or to get the URL for a particular mpeg stream.

Some clients will access the XML-RPC interface directly; others with previously-established protocols (like the Rio) will access JRec through a 'driver', which acts as a protocol convertor. The jrec_rio.war webapp is a working example of such a driver.

Menu queries allow the end-user to browse through lists of tunes, playlists, genres and cds/albums to select the audio they wish to play. The engine supports various query forms and data formats in which to get this data, so that the device can display menus with minimal fuss.

Metadata queries let the player pull up details on the currently playing tune or playlist to display on its front panel or status window.

Media queries come in two types, corresponding to playlist and tune data. Playlist queries go through the XML-RPC interface and return a list of tunes, based upon a menu query for a album, artist, genre or playlist. Tune queries require a URL and hit the Content Engine directly with a http GET to retrieve MPEG data for play.

The Manager

Configuration of the JRec server and its clients is done through a web application, presently implemented using JSP/Struts.

This app permits the user to specify which folders to scan for music and when those scans should occur. The user can create and edit dynamic playlists, configure the player and do other things as well.

The Drivers

Drivers play a critical role in support of devices with established and/or limited protocols. They serve as a bridge between the device and the JRec Server.

For example, the Rio Receiver has its own particular way of retrieving menus and content from the host. A driver, in this case the jrec_rio.war web application, will translate a Rio request to an XML-RPC call and submit to the server. The response from the server is then formatted for the Rio's consumption and sent to the Rio.

Note that a driver neither has to be a servlet nor need it be written in Java. It could conceivably be a standalone daemon written in C that talks to the JRec Server via XML-RPC. If your environment has an XML-RPC library, and most do, you can use JRec as a host server.

JRec API - XML-RPC Interface

With the 0.1.7 and 0.2.0 Alpha releases, the XML-RPC interface has been extensively reworked into a form that can be considered (fairly) stable.

At present, the only documentation can be found in the set of Java wrapper classes, mentioned in the next section.

Once a proper format is found to document the Raw XML-RPC interface, I'll write it up here. (If you can point me to good examples of XML-RPC interface docs, please do so. Thanks.)

XML-RPC Interface Wrappers

The purpose of a 'wrapper' is to hide complexity and to ease implementation by providing a familar and consistent interface to the developer.

Java wrapper

The XML-RPC interface has been wrapped in a set of Java classes to ease the developer's integration effort.

Here's the JavaDoc for the API: java/index.html

For tips on development, check out the sdk-java-guide.

An implementation of this interface is provided in a set of JARs (available in the JRec binary distributions or buildable from the source distribution.)

    lib/jrapcomm.jar - classes common to JRec client applications
    lib/jrcommon.jar - classes common to JRec client apps and server
    lib/jrutil.jar - general use utility classes

A cautionary note: these wrappers will continue to evolve during this alpha phase of development, but will stabilize prior to the first beta.

Driver Callback

There are several asynchronous callback interfaces which a driver (or player) can publish. Each one of them is optional but recommended.

Status - published by driver/player that can respond for status requests
Controller - published by driver for devices that can control other devices (X10 Controller, e.g.)
Command - published by driver/player that can respond to commands, either direct, IR, X10 or some other medium
Setting - published by driver/player that wants settings to appear in the webapp
Metadata (coming) - published by driver/player that wants to receive metadata/ID3 info via callback. Useful for streams.

main install faq rio redrat sdk