EasyH10 - manage the iRiver H10 MP3 player

Authors

Programauthor:
              Nyaochi (nyaochi at users dot sourceforge dot net)

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

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.

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.

Name

       EasyH10 - manage the iRiver H10 MP3 player

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/)

Options

Databaseconstructionoptions:-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.

Playlistconversionoptions:-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.

Tunerpresetoptions:-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.

H10Playermodeloptions:-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.

H10locationoptions:-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-specificoptions:-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).

Miscellaneousoptions:-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.