PearlLib and Tools

Property files are used by the Karma to describe individual files, as well as to document device properties and settings. This page describes the various property file keys as of firmware 1.41.

The format of the properties file returned is quite simple. It's ASCII text, with key=value pairs on separate newline-terminated lines. An example is available.

The Get All Files message returns information for many songs. In this case, the property file uses blank lines to separate individual songs.

There appear to be three data types for values in a property file:

• Numeric: a number, either in decimal or prefixed with 0x for hex.
• String: text data, a sequence of UTF-8 characters terminated by the line's ending newline.
• Binary: binary data, a sequence of characters terminated by the line's ending newline. Characters that might cause problems (so far, ASCII 0x00 through 0x1B) are escaped as \xDD (where DD is the hex value) -- as, presumably, is 0x5C (the backslash itself), though I haven't seen this as yet.
• Tokens: a sequence of semicolon-delimited text strings, as a sort of enumeration. The sequence includes both leading and trailing semicolons.

Device Information Properties

The following properties are sent in the device information file for firmware v1.41:

• capabilities (tokens): lists the capabilities of the device. Firmware v1.25 lists: read_content, utf8, rewrite_metadata, file_replace, playlists, root_playlist, and played_statistics.
• codecs (tokens): lists the device's audio codecs. Firmware v1.25 lists: mp3, wma, vorbis, flac, and wave. Files may have codecs not included in this list; in particular, files loaded using Rio Taxi claim the codec 'taxi.' However, all files of "type=tune" seem to have codecs in this list.
• device_generation (numeric): a Unix-style timestamp that appears to indicate the time the database was last modified.
• device_id (numeric): a value of unknown purpose which, on my device, reads 0x5210.
• firmware_version (string): 1.25, in my case.
• hwrev (numeric): 0x4, in my case.
• manufacturer (string): The name of the manufacturer.
• max_playlist_entries (numeric): 15000, in my case.
• name (string): the name of the device.
• recovery (numeric): a flag indicating recovery mode, 0 normally.
• rns_prefix (string): unknown, KRM in my case.
• rns_version (string): From the left, characters 0-3 are unknown, 4-6 are the firmware version, and the last two are unknown. 805014100 in my case.
• serial (numeric): unknown. Does not match the device's serial number. 0009576 in my case.
• storage_name (string): Hard disk in my case.

Song Metadata

The following keys have been seen in the Get All File Info and Get File Info messages.

• artist, for songs only
• bitrate, which is either 'fs' (fixed) or 'vs' (variable) followed by a the Kbps -- i.e. fs128, fs256, vs192, vs112. Taxi files seem to be fs128 for some reason.
• codec, such as mp3 -- this maps directly to the list of codecs specified in the Device Info response, with one exception. Taxi files have a codec of 'taxi'.
• ctime, a Unix-style timestamp that appears to indicate when the file was loaded onto the device.
• duration, the playtime of the song in milliseconds.
• fid, the File ID used to retrieve or modify the song.
• fid_generation. For songs (type=tune) and taxi files (type=taxi), this seems to be equal to the ctime or shortly before, and may reflect when the space was allocated. For playlists its use has not yet been determined.
• file_id, which appears to be identical to tracknr in all cases.
• genre
• length, which appears to be the length of the file in bytes.
• marked, a flag set by the Marked For Attention checkbox in RMML.
• normalisation, New in 1.4.1. The use is unknown; it's zero on all my tracks. The name implies that it might be used in some sort of Replay Gain thing.
• offset, which on some files indicates the byte offset to the actual song data. This is probably an optimization to aid gapless playback. This does not appear on Vorbis files.
• options, which is a bitmask of track flags. The only one known, bit 11 (2048 decimal), indicates Bad Track.
• play_count, the number of times the song has been played to completion.
• play_count_limit, the number of times a song can be played to completion. Seems to be DRM-related.
• play_last, a Unix-style timestamp of the last time the file was played.
• profile, the waveform of the song as displayed in Profile View on the play screen. This is binary with nulls escaped as \x00. Newlines are probably also escaped, but my sample set doesn't contain any. The profile attribute is present on any song that's been played while the Play Screen was displaying the Profile View. If parts of the song haven't been played yet in this mode, they're nulls. I'll work out the exact format a bit later.
• profiler_version, the version of the profiling algorithm used by AGC. This, along with rms and stddev, are added to files after they have been played all the way through.
• rid, a 16-byte hex string. While this is the right length for an MD5, it doesn't reflect the MD5 of the song itself unless the Karma modifies it on-device. This is only present on songs.
• rms, the mean loudness of a song computed by the profiler. The name strongly suggests that a root-mean-square algorithm is being used. Always appears with profiler_version. The unit used is not yet known, but may simply be the output samples of the PCM waveform (and thus probably 0..32767).
• samplerate, the sample rate of the decoded waveform in Hz.
• source, the name of the album.
• stddev, the standard deviation of the loudness of the song from the mean. Always appears with rms. The unit used is not yet known, but is virtually guaranteed to be the same as in rms.
• title, the name of the song, file, or playlist.
• tracknr, a track number for songs or zero for other types of files.
• trailer, which seems to appear only on the songs that came preloaded on the Karma and always equals 128
• type, either 'tune', 'taxi', or 'playlist'
• year, for songs, from the metadata.

Please read the disclaimer.