NAME
EasyH10 - manage the iRiver H10 MP3 player
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)
SEE ALSO
Visit EasyH10’s web page at http://easyh10.sourceforge.net for more
information.