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.
