Table of Contents: EasyH10 [CUI] manual
Building EasyH10 [CUI]
Compiling EasyH10 [CUI]
EasyH10 requires libid3tag and libiconv to be installed on one's operating system. As of version 1.0 beta 6, EasyH10 does not require a patch for libid3tag. The build & install procedure is as simple as:
$ tar xvzf easyh10-1.0.tar.gz $ cd easyh10-1.0 $ ./configure $ make $ make install
EasyH10 can also be built against libid3tag with an enhancement patch enabled. The patch distributed by EasyH10 project has two enhancements over the official version to deal with problematic MP3 files:
- ID3v1 tags (for a fields which are empty, unset) in the ID3v2 tags but filled in ID3v1 tags
- Erroneous tags generated by buggy software and not recognized by the official libid3tag.
Build libid3tag-0.15.1b special version as follows:
$ tar xvzf libid3tag-0.15.1b.tar.gz $ cd libid3tag-0.15.1b $ patch -p1 < ../libid3tag-0.15.1b_easyh10-0.10.patch $ ./configure --disable-shared $ make # Just compile and do not install it! $ export PATH_TO_ID3TAG=`pwd` # For the convenience.
Then one can force a link between libid3tag library statically by the following configure options:
$ tar xvzf easyh10-1.0.tar.gz $ cd easyh10-1.0 $ ./configure --with-id3tag-header=$PATH_TO_ID3TAG --with-id3tag-library=$PATH_TO_ID3TAG/.libs $ make $ make install
EasyH10 also depends on iconv in libc or libiconv for converting locale-specific characters (e.g., ISO-8859-1, CP932, etc.) into UCS-2 little endian. The configure script should find iconv library and header file, but some operating systems may not have these files installed. Should the configure script fail for lack of iconv staffs, one will need to download the iconv source code and build it. One can download the source code from the libiconv web site.
$ tar xvzf libiconv-1.9.1.tar.gz $ cd libiconv-1.9.1 $ ./configure $ make $ export PATH_TO_ICONV=`pwd` # For the convenience.
Then he or she can force a link between iconv library statically by the following configure options:
$ ./configure --with-iconv-header=$PATH_TO_ICONV/include --with-iconv-library=$PATH_TO_ICONV/lib/.libs
Copying an H10 model file to H10's HDD
Before using EasyH10, it is recommended that one choose an H10 model template in "/usr/local/share/easyh10/model/*.model" and copy it into H10's HDD so that EasyH10 can automatically recognize the model and firmware of the H10 player. EasyH10 assumes $PATH_TO_H10/easyh10.model or $PATH_TO_H10/easyh10/model/easyh10.model ($PATH_TO_H10 is the path to H10 root directory) to be the default template file. Given that the H10 player is mounted on /mnt/usbdisk and you have H10 5GB UMS firmware version 2.05, he or she can do this task by:
$ cp /usr/local/share/easyh10/model/H10UMS_5GB_FW2.04-2.05.model /mnt/usbdisk/easyh10.model
or
$ mkdir /mnt/usbdisk/easyh10/model $ cp /usr/local/share/easyh10/model/H10UMS_5GB_FW2.04-2.05.model /mnt/usbdisk/easyh10/model/easyh10.model
Using EasyH10 [CUI]
Character encoding of operating system and non-unicode tags
If he or she has an operating system working in a character set other than UTF-8, he or she must specify it with -e option. If he or she uses a character set other than UTF-8 for non-unicode ID3v2 tags or WAVE files, he or she must specify it with -w option.
For example, if one has Japanese Shift_JIS MP3 files, he or she needs to add "-w CP932" in the command-line arguments.
To rebuild a media database and reconvert playlists
Rebuild the media database with track number ordering. Reconvert playlists in /mnt/usbdisk/Media/Music and /mnt/usbdisk/Media/Playlist/* into respective PLP playlists. Be sure to change the arguments for -e and -w options so that they fit your environment.
$ easyh10 -C -on -PMrf -e UTF-8 -w ISO-8859-1 /mnt/usbdisk EasyH10 [CUI] 1.0 Copyright (c) 2005 by Nyaochi H10 model template: /mnt/usbdisk/easyh10.model Path to database: /mnt/usbdisk/System\DATA/ Path to music: /mnt/usbdisk/Media\Music/ Path to playlist: /mnt/usbdisk/Media\Playlist/ Playlist extension: .plp Enumerating music files: 28 files found. Reading H10 model template: H10 (UMS) 5GB firmware 2.04 - 2.05 Obtaining media information from 28 files: 28 files obtained. Updating database Writing H10 media database: 100%: (H10DB.hdr) Enumerating playlists: 4 playlists found. Enumerating music files: 28 files found. Converting 4 playlists: 4 playlists successfully converted.
To update a media database playlists
$ easyh10 -U -on -PMf -e UTF-8 -w ISO-8859-1 /mnt/usbdisk EasyH10 [CUI] 1.0 Copyright (c) 2005 by Nyaochi H10 model template: /mnt/usbdisk/easyh10.model Path to database: /mnt/usbdisk/System\DATA/ Path to music: /mnt/usbdisk/Media\Music/ Path to playlist: /mnt/usbdisk/Media\Playlist/ Playlist extension: .plp Enumerating music files: 28 files found. Reading H10 model template: H10 (UMS) 5GB firmware 2.04 - 2.05 Reading H10 media database 100%: H10DB_*.idx Obtaining media information from 0 files: 0 files obtained. Updating database Writing H10 media database: 100%: (H10DB.hdr) Enumerating playlists: 4 playlists found. Enumerating music files: 28 files found. Converting 0 playlists: 0 playlists successfully converted.
To dump a media database
If you are interested in the database structure...
$ easyh10 -D /mnt/usbdisk
EasyH10 [CUI] 1.0 Copyright (c) 2005 by Nyaochi
H10 model template: /mnt/usbdisk/easyh10.model
Path to database: /mnt/usbdisk/System\DATA/
# H10DB.hdr
unknown1: 0
unknown2: 0
pathname_dat: System\DATA\H10DB.dat
unknown3: 1
pathname_hdr: System\DATA\H10DB.hdr
unknown4: 0x00000428
num_dat_entries: 28
num_dat_inactive_entries: 0
num_dat_fields: 22
fd[ 0]: {0x0000F001, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DEV.idx"}
fd[ 1]: {0x0000F002, 1, 128, 0, 0, 1, 0, 0, L"System\DATA\H10DB_FPTH.idx"}
fd[ 2]: {0x0000F003, 1, 128, 0, 0, 1, 0, 0, L"System\DATA\H10DB_FNAM.idx"}
fd[ 3]: {0x0000F00A, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_FRMT.idx"}
fd[ 4]: {0x0000002E, 1, 40, 0, 0, 1, 0, 0, L"System\DATA\H10DB_TIT2.idx"}
fd[ 5]: {0x0000003C, 1, 40, 0, 0, 1, 0, 0, L"System\DATA\H10DB_TPE1.idx"}
fd[ 6]: {0x0000001C, 1, 40, 0, 0, 1, 0, 0, L"System\DATA\H10DB_TALB.idx"}
fd[ 7]: {0x0000001F, 1, 20, 0, 0, 1, 0, 0, L"System\DATA\H10DB_TCON.idx"}
fd[ 8]: {0x0000E002, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DU3.idx"}
fd[ 9]: {0x0000E003, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DU4.idx"}
fd[10]: {0x0000E004, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DU5.idx"}
fd[11]: {0x0000E005, 2, 4, 0, 0, 0, 0, 0, L""}
fd[12]: {0x00000043, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_TRCK.idx"}
fd[13]: {0x0000004E, 2, 4, 0, 0, 0, 0, 0, L""}
fd[14]: {0x0000F009, 2, 4, 0, 0, 0, 0, 0, L""}
fd[15]: {0x0000F007, 2, 4, 0, 0, 0, 0, 0, L""}
fd[16]: {0x0000F006, 2, 4, 0, 0, 0, 0, 0, L""}
fd[17]: {0x0000F005, 2, 4, 0, 0, 0, 0, 0, L""}
fd[18]: {0x0000E000, 2, 4, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DU1.idx"}
fd[19]: {0x0000E001, 1, 40, 0, 0, 1, 0, 0, L"System\DATA\H10DB_@DU2.idx"}
fd[20]: {0x00000083, 2, 4, 0, 0, 0, 0, 0, L""}
fd[21]: {0x00000084, 1, 64, 0, 0, 0, 0, 0, L""}
...
# End of H10DB.hdr
# H10DB.dat {num_dat = 28}
## Entry 1
inactive: 0
unknown1: 0
unknown2: 0
file_path: Media\Music\Jem\FinallyWoken\
file_name: 01_FinallyWoken.mp3
media_type: 0
title (htn=0): They
artist: Jem
album: Finally Woken
genre:
rating: 0
revision: 0
recent_play: Sat Jan 1 08:00:00 2000
unknown4: 1118761606
number: 0
filesize: 3067233
duration: 196
samplerate: 44100
bitrate: 124978
unknown5: 1
unknown6:
unknown7: 0
unknown8:
Validation failed: unknown4
Validation failed: unknown5
## End of entry 1
...
To see the manpage
$ man easyh10
EASYH10(1) User Commands EASYH10(1)
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 pro-
cessing, 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 deter-
mined 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 tem-
plate (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 speci-
fies a model template manually.
OPTIONS
Database construction options:
-C, --construct
Construct a media database from music files located under the
music directory. EasyH10 enumerates all MP3/WMA/WAV files in
To see the help message
$ easyh10 --help
EasyH10 [CUI] 1.5 Copyright (c) 2005-2006 by Nyaochi
USAGE: cui/easyh10 [OPTIONS] [LOCATION]
LOCATION Absolute path to the H10 root directory (e.g., /mnt/usbdisk/)
Database construction options:
-C, --construct Construct a new media database from music files
-U, --update Update the existing media database incrementally
-o, --order=TYPE Specify a playback order:
d, default Leave an H10 firmware for playback order (DEFAULT)
t, tracktitle Force an alphabetical order of track titles
f, filename Force an alphabetical order of file names
n, tracknumber Force a numerical order of track numbers
c, complete Force a complete random order (always shuffle)
a, album Force a random order when playing an album
l, all Force a random order when playing all titles
-z, --source=METHOD Specify a method for obtaining media information:
m Tag information in music files (DEFAULT)
[g]p Parse pathnames to obtain (genres and) artists
[g]pa Parse pathnames to obtain (genres,) artists, albums
[g]pa[n]t Parse pathnames to obtain (genres,) artists, albums
and parse filenames to obtain (numbers and) titles
Playlist conversion options:
-P, --playlist Convert playlist files in PLAYLIST directory
-M, --music Convert playlist files in MUSIC directories
-r, --reconvert Discard the existing PLP/PLA playlist and reconvert
-g, --guess-missing Guess pathnames of missing music files in a playlist
-f, --find-missing Find pathnames of missing music files in a playlist
-k, --skip-missing Skip missing music files in a playlist and continue
-x, --regex-playlist Enable Regular Expression Playlist (REP)
-l, --auto-shuffle Shuffle music files in [(name).sfl*.(ext)] playlists
Tuner preset options:
-I, --import-tuner=FN Import a tuner preset from a file
-E, --export-tuner=FN Export the current tuner preset to a file
-a, --merge-tuner Merge the current tuner preset with a file
H10 player model options:
-t, --model=MODEL Apply a model template for specifying an H10 model
-T, --gen-model=MODEL,FW_MIN_VERSION,FW_MAX_VERSION
Create a model template from an existing database
-X, --install-model Install the specified model template into the player
H10 location options:
-s, --systempath=SYSTEM Specify path to the system directory
-d, --dbpath=DATABASE Specify path to the database
-m, --musicpath=MUSIC Specify root path to the music files
-p, --playlistpath=PLAYLIST Specify path to the playlist files
Language-specific options:
-e, --encoding=SE Specify character encoding used by the operating system
-w, --tagencoding=TE Specify character encoding for parsing non-Unicode tags
-b, --bidi Arrange BiDi characters to be displayed correctly (exp)
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
Copyright (c) 2005-2006 by Nyaochi. (last update: 2006/10/08 20:43:25 )