Ubuntu Manpage: EasyH10 - manage the iRiver H10 MP3 player

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)