SYNOPSIS

easyh10 [ options ] [ location ]

DESCRIPTION

EasyH10 is a command-line utility to generate a media database and playlist for an iRiver H10 digital audio player. Transferring MP3/WMA/WAV files into the music directories and creating M3U/M3U8/PLS playlist files under the music directories or playlist directory must be done manually in advance. EasyH10 then constructs a media database from the music files and converts the playlist files into PLP/PLA playlist files, which are recognized by the H10 player.

Database construction generates a set of database files in the database directory, obtaining the media information (e.g., title name, artist name, album name, genre name, track number, etc.) from all MP3/WMA/WAV files found in the music directories. Among database-related options, the update mode (-U option) reads an existing media database, compares it with the current content of the music directories, inserts entries for music files that have been added or updated since the previous processing, and erases entries for music files that have been removed. EasyH10 can force music tracks to be played in an order that a user specified with -o option. The way of obtaining the information of a music file is also configurable (see -z option).

Playlist conversion targets all M3U/M3U8/PLS playlist files located in the playlist directory (with -P option) and/or music directories (with -M option). For each target, it finds the music files referred by the playlist and writes out an iRiver-specific playlist file into the playlist directory with the same file name. The converted playlist files will have .plp extension for UMS players or .pla for MTP players. The behavior when EasyH10 could not find a music file referred by a playlist can be specified with options -g, -f, and -k. Do not put two or more playlist files sharing the same file name to avoid a collision of converted playlist files.

Location specifies the path to the root directory where an H10 player is mounted as an external HDD. Three important directories, the database directory, music directory, and playlist directory are determined automatically as relative paths from the root directory. As for these directories, refer to the description for options -d, -m, and -r that configure the default values.

A model template must be specified for EasyH10 to identify the model of the iriver H10 player to be managed. EasyH10 assumes a default template (easyh10.model) to be placed in the current directory, the root directory of the player, easyh10/model directory from the player root directory, etc. As for the complete list of directories for the default template, refer to the description of option -t, which specifies a model template manually.

OPTIONS

Database construction options:

-C, --construct

Discard an existing database and construct a new one from music files located under the music directory. EasyH10 enumerates all MP3/WMA/WAV files in the music directories, obtains the media information (e.g., title name, artist name, album name, genre name, track number, bitrate, sample rate, etc.) from the found files, and generates a set of database files in the database directory.

-U, --update

Update a media database from music files located under the music directory. EasyH10 obtains the media information from files that have been updated or added since the last database construction.

-o, --order=TYPE

Choose a playback and displaying order in the MUSIC mode. Selecting an order except for default inserts a space just before track titles. This space is a special character to control the playback order, but you may not notice it because the player uses a proportional font by default.

d, default

Leave the player to arrange music tracks in a default order determined by the firmware. EasyH10 will not make any attempt to change the playback order. The playback order will be the same as that created by iriver plus and Windows Media Player 10. If you have an H10 player running on UMS 2.04 firmware, the playback order will be a numerical order of track numbers.

t, tracktitle

Force an alphabetical order of track titles. This order is useful if you added the track number at the head of each track name (e.g., "01 song name").

f, filename

Force an alphabetical order of file names. This order is useful if you added the track number at the head of each file name (e.g., "01_songname.mp3").

n, tracknumber

Force a numerical order of track numbers. The track number must be associated with each music file. This order is the most recommended option if you want to listen to the music as if you listened to a CD. It arranges music tracks in a numerical order of track numbers even when entering all-tracks-by-an-artist navigation.

c, complete

Force a random order (shuffle) for any cases. The iRiver H10 player will turn into a shuffle-only player.

a, album

Force a random order when playing music tracks in an album and numerical order of track numbers when entering all-tracks-by-an-artist or all-tracks-with-a-genre navigation.

l, all

Force a random order when playing all titles and numerical order of track numbers when playing music tracks in an album.

-z, --source=METHOD

Specify a method for obtaining media information. This option was introduced for users who want to make use of directory layout rather than tag information. EasyH10 provides nine templates for specifying the source from which the music information is obtained.

m

Tag information in music files (DEFAULT). This is the recommended option if the tag is written into music files properly.

[g]p

Parse path names to obtain (genres and) artists. This template assumes directories in the music directory to represent artist names. Other fields (i.e., album name, genre name, track title, and track number) are extracted from the tag.

[g]pa

Parse path names to obtain (genres,) artists, albums. This template assumes directories in the music directory to represent artist names and directory names from artist directories to represent album names. A path letter '/' in the album directories are replaced with a space. Other fields are extracted from the tag.

[g]pa[n]t

Parse path names to obtain (genres,) artists, and albums; parse file names to obtain (numbers and) titles. This template assumes file names to represent track titles in addition to [g]pa template. Specifying n assumes two letters at the head of file names to represent track numbers. It skips space and '_' letters followed by the two digits to extract track titles.

Playlist conversion options:

-P, --playlist

Convert playlist files in the playlist directory. Setting this option converts M3U/M3U8/PLS files located in the playlist directory and writes respective PLA/PLP playlist files.

-M, --music

Convert playlist files in the music directories. Setting this option converts M3U/M3U8/PLS files located under the music directories (including sub-directories) and writes respective PLA/PLP files to the playlist directory.

-r, --reconvert

Overwrite the existing PLP/PLA playlist files to force conversion.

-g, --guess-missing

Guess path names of missing music files in a playlist. Setting this option tries to correct the location of music files referred by a playlist by trying a possible combinations of the path to the music folder and path to the music file referred by the playlist.

-f, --find-missing

Find path names of missing music files in a playlist. Setting this option tries to correct the location of a music file referred by a playlist by searching for the music file in the music directories that have the same file name. Finding two or more music files that have the target file name, EasyH10 selects a music file with a path name that is the most similar to the original one.

-k, --skip-missing

Skip missing music files in a playlist. Setting this option indicates EasyH10 to continue the playlist conversion only with music files found in the H10 player. The default behavior for a missing music file is to cancel the conversion for the playlist.

-x, --regex-playlist

Enable Regular Expression Playlist (REP). Regular Expression Playlist (REP) is a kind of smart playlist based on path/file names. EasyH10 generates a playlist with music files that are supported by the H10 player and match the condition(s) described in *.rep file. If a music collection has the folder structure with (genre,) artist, and album names, EasyH10 can automatically create a playlist with all tracks in the player, by a specific artist, or by a more complicated condition.

-l, --auto-shuffle

Shuffle music files in [(name).sfl*.(ext)] playlists. If a playlist filename contains ".sfl" substring just before an extension (e.g., hoge.sfl.m3u, fuga.sfl.pls, all.sfl.rep), EasyH10 automatically randomizes the order of music tracks referred by the playlist. In other words, EasyH10 users can create a random playlist only if they name it as "(name).sfl.(extension)" pattern.

Tuner preset options:

-I, --import-tuner=FN

Import a tuner preset from a file. EasyH10 will discard the existing preset in the player without -a (--merge-tuner) option.

-E, --export-tuner=FN

Export the current tuner preset to a file. EasyH10 will discard the existing preset in the local file without -a (--merge-tuner) option.

-a, --merge-tuner

Merge the current tuner preset with a file.

H10 Player model options:

-t, --model=MODEL

Specify a model template. EasyH10 uses this file to identify an iRiver H10 model. By default, model template files are copied into ${PREFIX}/share/easyh10/model by the installer. You may specify one of these template files. If no model template is specified, EasyH10 finds a default template (easyh10.model) in the following directory/order: the current directory; ${H10ROOT}/easyh10/model; ${H10ROOT}/model; and ${H10ROOT}. Therefore, you may copy a template file to these locations so that EasyH10 will read it automatically.

--gen-model=MODEL,FW_MIN_VERSION,FW_MAX_VERSION

Create a model template from an existing database. This option is only for EasyH10 developpers. Do not use this option.

-X, --install-model

Install the model template specified by -t option into the player. This will make a copy of the template file as ${H10ROOT}/easyh10.model.

H10 location options:

-s, --systempath=SYSTEM

Specify the path to the system files. This option overwrites the default value ${H10ROOT}/System.

-d, --dbpath=DATABASE

Specify the path to the database. This option overwrites the default value ${H10ROOT}/System/DATA.

-m, --musicpath=MUSIC

Specify the path to the music files. This option overwrites the default value ${H10ROOT}/Media/Music for UMS players or ${H10ROOT}/Music for MTP players.

-p, --playlistpath=PLAYLIST

Specify the path to the playlist files. This option overwrites the default value ${H10ROOT}/Media/Playlist for UMS players or ${H10ROOT}/Playlists for MTP players.

Language-specific options:

-e, --encoding=SE

Specify a character encoding used by the operating system. EasyH10 converts path/file names from the specified encoding into UCS-2 using iconv. The default value is determined by an automatic detection of the system character-encoding.

-w, --tagencoding=TE

Specify a character encoding for parsing non-unicode tags. EasyH10 converts non-unicode tags embedded in ID3v1, ID3v2, and Riff WAVE into UCS- using iconv. The default value is ISO-8859-1.

-b, --bidi

Store the field values in the database so that the player can display Hebrew strings correctly (experimental).

Miscellaneous options:

-D, --dump

Output a database dump in plain text format.

-V, --version

Show version number and exit.

-h, --help

Show this help message and exit.

-v, --verbose

Verbose mode.

NOTE

It is recommended to copy a firmware model template to the root of the device in order to avoid having to specify the firmware every time the tool is used. The following example is for the International version of the 5 GB player.

cp /usr/share/easyh10/model/H10Intl_5GB_FW2.04-2.05.model /mnt/usbdisk/easyh10.model

(Depending on your installation method, the .model files may be in /usr/share/easyh10/, /usr/local/share/easyh10/ or /usr/local/share/easyh10/model/)

EXAMPLE

easyh10 -C -on /mnt/usbdisk

Rebuild a media database with track-number ordering for the H10 player mounted on /mnt/usbdisk.

easyh10 -U -ol -PMrf /mnt/usbdisk

Update a media database with all-shuffle ordering. Reconvert playlist files in /mnt/usbdisk/Media/Music and /mnt/usbdisk/Media/Playlist/* into respective PLP playlist files.

AUTHORS

Program author:

Nyaochi (nyaochi at users dot sourceforge dot net)

Manpage author:

Benjamin Seidenberg (astronut at dlgeek dot net)
Nyaochi (nyaochi at users dot sourceforge dot net)