From NMTWiki

Contents 1 Developing Skins for Music Jukebox 1.1 Album Detail XML Files Generated by Music Jukebox 1.2 Index XML Files Generated by Music Jukebox 1.3 The Playlist.XML Files Generated by Music Jukebox 1.4 The Searchpage.XML File Generated by Music Jukebox 1.5 The List Index XML Files Generated by Music Jukebox 1.6 The Language Elements in the XML Files 1.7 The .install file 1.7.1 CONFIG Entries 1.7.2 INSTALL Entries

Developing Skins for Music Jukebox

Album Detail XML Files Generated by Music Jukebox

Music Jukebox will create a separate XML file for each music album folder it processes. This file will be used to generate the HTML file for the album, using the detail.xslt file contained in the skins folder. The XML file contains 1 PREFERENCES element, 1 ALBUM element and 1 SONGS element, which contains one or more SONG elements. Note that the PREFERENCES element also contains the LANGUAGE elements. Each is defined below;

PREFERENCES Element

Element	Description
file	Name of HTML file being generated.
focuscolor	HTML color name or number to display HTML links.
homepage	URL to exit the menu to.
imageheight	Size of the album cover art image, in pixels.
largebuttonsize	Size of the navigation buttons, in pixels.
maxtextlen	Maximum number of characters to display for a song title. Zero means display all characters, regardless of length of song title.
next	Name of HTML file to link NEXT button to. Or blank if on last page.
page	Current page number.
pchpathtomenu	Value of the Popcorn Hour Path To Menu field on the Music Jukebox application main screen.
pchpathtomusic	Value of the Popcorn Hour Path to Music field on the Music Jukebox application main screen.
previous	Name of HTML file to link PREVIOUS button to. Or blank if on page 1.
smallbuttonsize	size of the play button, in pixels.
totalpages	Number of pages need to define all songs in this album.
indexpreferences	The PREFERENCES element of each Album Detail Page XML file includes a child element named indexpreferences. This child element contains the most common settings defined for index pages. Element Description cellheight Size, in pixels, of the table cell used for each album cover image. cols Number of columns of album cover images to display on an index page. dolphmenu Should Music Jukebox create the index menus where the current album image is displayed larger than the others? imageheight Size, in pixels, of album cover art displayed on an index page. maxtextlen Maximum number of characters to display on an index page for album or artist name. Zero means do not truncate. offscreenscrolling Should Music Jukebox enable support for off-screen scrolling? If TRUE, Music Jukebox disables the Javascript that keeps track of the currently highlighted album to suport the PLAY button. playlistlink The URL to the Playlists page. playlisttvid The TVID defined for the Playlists page link. rows Number of rows of album cover images to display on an index page. searchpage The URL to the Search page. searchpagetvid The TVID defined for the Search page link. sortbyyear Are the albums of an individual artist sorted by album release year.

Each Album Detail Page XML file contains a single element named ALBUM that defines the music album being generated. It includes such items as the cover art images, album title, artist, etc.

ALBUM Element

Element	Description
albumart	The URL of the large album cover image, generally displayed on the Album Detail page.
artist	The name of the artist.
fanart	The URL of the background image to use for this album.
folder	The PCH path to the folder that this album is located in.
genre	The name of primary Genre of this album.
partyshuffle	The URL of the Party Mode command. This may be blank if party mode is disabled.
partyshuffletvid	The TVID of the party mode link.
playlist	The PCH path to the playlist of the entire album.
playlisttvid	The TVID defined for the albums playlist link.
shuffle	The URL of the shuffle command. This field may be blank if shuffle mode is disabled.
shuffletvid	The TVID defined for the shuffle link.
slideshow	The URL of the photo slideshow playlist file. This will be blank if there is no slideshow associated with the album playlist.
sort	The name being used to sort the album. This may or may not be the album title.
thumbnail	The URL of the small album cover image, generally displayed on the Index pages.
title	Album title.
year	The year this album was released. This field may be blank.

Each Album Detail XML file will contain one element named SONGS. This will contain one or more SONG elements, each corresponding to a single song file located in the album folder. The SONGS element will contain a single attribute, COUNT, which will be set to the number of SONG elements contained within the SONGS element.

SONG Elements

Element	Description
artist	The name of the artist or group. This is retrieved from the embedded tags within the file or calculated from the folder structure.
averagebitrate	The average bitrate of the music file, if available (currently MP3, OGG and FLAC only).
duration	The length of the song, retrieved from the embedded tags within the file.
file	The PCH-specific path to the music file.
fileformat	The type of music file (MP3, FLAC, etc).
index	The track number of the song. This is retrieved from the embedded tags within the file or calculated from the file name.
name	The name of the song. This is retrieved from the embedded tags within the file or calculated from the file name.
ondemand	Specifies what type of file this is. Ondemand will be 'AOD' for a music file or 'VOD' for a video file.
publisher	The contents of the ID3 Publisher or OGG/FLAC Organization tag.
zcd	This element will be set to 2 if the file is a video container file and left blank for all other file types.

Index XML Files Generated by Music Jukebox

Music Jukebox will create a separate XML file for each page of the index menus. These pages generally contain the album covers as hyperlinks to the album detail pages and links to the other indexes. An example of this type of page is the Main menu of Music Jukebox Default skin. These index XML files are combined with the index.xslt file of the current skin to generate the HTML files for the menu pages.

Each index XML file will contain 1 PREFERENCES element, 1 INDEX element, 1 ALBUMS element, 1 INDEXES element and 1 GENRES element, each defined below. It may also contain 1 ARTISTINDEXES element and 1 DECADES element, also defined below. The PREFERENCES element also contains the LANGUAGE elements.

PREFERENCES Element

Element	Description
albumsinindex	Total number of albums represented in this index.
cellheight	Size, in pixels, of the table cell used for each album cover image.
cols	Number of columns of album cover images to display on an index page.
dolphmenu	Should Music Jukebox create the index menus where the current album image is displayed larger than the others?
file	Name of HTML file being generated.
focuscolor	HTML color name or number to display HTML links.
homepage	URL to exit the menu to.
imageheight	Size, in pixels, of album cover art displayed on an index page.
largebuttonsize	Size of the navigation buttons, in pixels.
masterplaylist	the URL of the master playlist, if enabled.
maxtextlen	Maximum number of characters to display for an artist or album name. Zero means display all characters, regardless of length.
next	Name of HTML file to link NEXT button to. Or blank if on last page.
offscreenscrolling	Should Music Jukebox enable support for off-screen scrolling? If TRUE, Music Jukebox disables the Javascript that keeps track of the currently highlighted album to suport the PLAY button.
page	Current page number.
pchpathtomenu	Value of the Popcorn Hour Path To Menu field on the Music Jukebox application main screen.
pchpathtomusic	Value of the Popcorn Hour Path to Music field on the Music Jukebox application main screen.
playlistlink	The URL to the Playlists page.
playlisttvid	The TVID defined for the Playlists page link.
previous	Name of HTML file to link PREVIOUS button to. Or blank if on page 1.
rows	Number of rows of album cover images to display on an index page.
searchpage	The URL to the Search page.
searchpagetvid	The TVID defined for the Search page link.
smallbuttonsize	Size of the play button, in pixels.
sortbyyear	Are the albums of an individual artist sorted by album release date instead of album name.
totalpages	Number of pages need to define all songs in this album.

Each Index XML file generated contains 1 INDEX element. This element defines the type of index page being generated and its title.

INDEX Element

Element	Description
title	The text to be displayed on top of the page.
type	One of Element Description Alpha An index sorted by artist name. Artist An index of all music by a certain artist. Decade An index of all music released in a certain decade. Genre An index of all music albums in a certain genre. MainArtists A list of all artists in the music collection MainDecades A list of all the decades represented in the music library. MainGenres A list of all the genres represented in the music library. MainIndex The main index of the music menu, showing links to the other indicies and a thumbnail view of all music albums.

Each Index XML file will contain one element named ALBUMS. This will contain one or more ALBUM elements, each corresponding to a single album folder. The ALBUMS element will contain a single attribute, COUNT, which will be set to the number of ALBUM elements contained within the ALBUMS element.

ALBUM Elements

Element	Description
albumart	The URL of the image of the album cover.
artist	The name of the artist.
file	the URL of the file being generated.
folder	The PCH path to the folder this album is located in.
genre	The genre of the album.
partyshuffle	The URL to the command to play this album repeatedly.
playlist	The PCH path to the playlist file for this album.
shuffle	The URL to the command to play this album in shuffle mode.
slideshow	The URL of the photo playlist to be displayed while the album music playlist is running. This will be blank if no slideshow is defined for the album.
sort	The text used to sort this album. This may or may not be the artist name and album name.
thumbnail	The URL of the thumbnail image of the album cover.
title	The name of the album.
year	The year the album was released.

Each Index XML file will contain one element named INDEXES. This will contain one or more INDEX elements, each corresponding to a link to a page of albums by letter of the alphabet. The INDEXES element will contain a single attribute, COUNT, which will be set to the number of INDEX elements contained within the INDEXES element.

INDEX Elements

Element	Description
file	The URL to the first page of the index.
name	The text to display at the top of the index pages.
tvid	The TVID to assign to this index.

Each Index XML file will contain one element named GENRES. This will contain one GENRESINDEX element and one or more GENRE elements, each corresponding to a link to a page of albums by genre. The GENRES element will contain a single attribute, COUNT, which will be set to the number of elements contained within the GENRES element.

GENRESINDEX Element

Element	Description
file	The URL to the first page of the list of genres index.
name	The text to display at the top of the list of genres pages.

GENRE Elements

Element	Description
file	The URL to the first page of the genres index.
name	The text to display at the top of the genre index pages.
tvid	The TVID to assign to this genre index.

Each Index XML file may contain an element named ARTISTINDEXES. This will contain one ARTISTINDEX element, corresponding to a link to a list of artists. The ARTISTINDEXES element will contain a single attribute, COUNT, which will be set to the number of elements contained within the element. Currently, this is always 1.

ARTISTINDEX Element

Element	Description
file	The URL to the first page of the list of artists index.
name	The text to display at the top of the list of artists pages.
tvid	The TVID to assign to the artists index.

Each Index XML file may contain an element named DECADES. This will contain one DECADEINDEX element, corresponding to a link to a list of album release years. The DECADES element will contain a single attribute, COUNT, which will be set to the number of elements contained within the element. Currently, this is always 1.

DECADEINDEX Element

Element	Description
file	The URL to the first page of the list of decades index.
name	The text to display at the top of the list of decades pages.
tvid	The TVID to assign to the decades index.

The Playlist.XML Files Generated by Music Jukebox

Music Jukebox will create a separate playlist.xml file for each page of your Playlists menu. These playlist XML files are combined with the playlist.xslt file of the current skin to generate the HTML files for the playlist pages.

Each playlist XML file will contain 1 PREFERENCES element and 1 PLAYLISTS element, each defined below. The PREFERENCES element also contains the LANGUAGE elements. The PLAYLISTS element contains one or more PLAYLIST elements, each representing a saved playlist file.

PREFERENCES Element

Element	Description
albumsinindex	Total number of playlist files in the playlists folder.
file	Name of HTML file being generated.
focuscolor	HTML color name or number to display HTML links.
homepage	URL to exit the menu to.
largebuttonsize	Size of the navigation buttons, in pixels.
masterplaylist	the URL of the master playlist, if enabled.
next	Name of HTML file to link NEXT button to. Or blank if on last page.
page	Current page number.
partymode	TRUE if menu should support Party (repeated random) playback.
pchpathtomenu	Value of the Popcorn Hour Path To Menu field on the Music Jukebox application main screen.
pchpathtomusic	Value of the Popcorn Hour Path to Music field on the Music Jukebox application main screen.
playlistlink	This is always blank.
playlisttvid	This is always blank.
previous	Name of HTML file to link PREVIOUS button to. Or blank if on page 1.
searchpage	The URL to the Search page.
searchpagetvid	The TVID defined for the Search page link.
shufflemode	TRUE if menu should support shuffle (random) playback.
smallbuttonsize	size of the play button, in pixels.
totalpages	Number of pages needed to list all playlists.

Each Playlist XML file will contain one element named PLAYLISTS. This will contain one or more PLAYLIST elements, each corresponding to a single playlist file. The PLAYLISTS element will contain a single attribute, COUNT, which will be set to the number of PLAYLIST elements contained within the PLAYLISTS element.

PLAYLIST Elements

Element	Description
file	the URL of the playlist file.
index	The sequential index number of the playlist.
name	The display name of the playlist. This is taken from the file name.
ondemand	The type of playlist file. It is one of; ondemand Description aod Audio On Demand, this is an audio playlist. pod Photo On Demand, this is a slideshow playlist. The slideshow element will contain the photo playlist to use for this slideshow.
partyshuffle	The URL to the command to play this playlist in party mode.
shuffle	The URL to the command to play this playlist in shuffle mode.
slideshow	The URL of the slideshow playlist to link to this music playlist. This element is only set if the playlist ondemand is set to POD.

The Searchpage.XML File Generated by Music Jukebox

Music Jukebox will create a single searchpage.xml file for the search page. This file is combined with the search.xslt file of the current skin to generate the HTML for the search page.

The searchpage XML file will contain 1 PREFERENCES element, which includes, among other elements, the LANGUAGE elements.

PREFERENCES Element

Element	Description
albumsinindex	Always 0.
file	URL of the search page.
focuscolor	HTML color name or number to display HTML links.
homepage	URL of the main index page.
largebuttonsize	Size of the navigation buttons, in pixels.
masterplaylist	the URL of the master playlist, if enabled.
next	Name of HTML file to link NEXT button to (always blank on the search page).
page	Current page number (always 1 on the search page).
pchpathtomenu	Value of the Popcorn Hour Path To Menu field on the Music Jukebox application main screen.
pchpathtomusic	Value of the Popcorn Hour Path to Music field on the Music Jukebox application main screen.
playlistlink	This is always blank.
playlisttvid	This is always blank.
previous	Name of HTML file to link PREVIOUS button to (always blank on the search page).
search	The URL of the search command.
searchpage	The URL to the Search page.
searchpagetvid	The TVID defined for the Search page link.
smallbuttonsize	size of the play button, in pixels.
totalpages	Number of search pages (always 1).

The List Index XML Files Generated by Music Jukebox

Music Jukebox will create a separate XML file for each page of the non-graphical index menus. These pages include the main artist and decades indexes. These list index XML files are combined with the list.xslt file of the current skin to generate the HTML files for the menu pages.

Each list index XML file will contain 1 PREFERENCES element, 1 INDEX element, 1 INDEXITEMS element, 1 INDEXES element and 1 GENRES element, each defined below. It may also contain 1 ARTISTINDEXES element and 1 DECADES element, also defined below. The PREFERENCES element also contains the LANGUAGE elements.

The Language Elements in the XML Files

The PREFERENCES section of each XML file generated by Music Jukebox includes the text to display for each button and heading produced by Music Jukebox. You should use the values defined in the PREFERENCES section of each page to ensure your skin works in other languages.

LANGUAGE Definitions (within the PREFERENCES Element)

Element	Description
lang_all	User-defined text used when creating links to automatically generated playlists.
lang_artists	User-defined name of the Artists index page.
lang_CD	User-defined text to display on the main page of Multi-CD album sets when individual CD's are not named.
lang_genre	User-defined name of the the list of Genres.
lang_masterplaylist	User-defined name of the AllMusic playlist.
lang_nogenre	User-defined name of the group to assign music to that have no genres attached.
lang_partyshuffle	User-defined name of the Party Mode button column on the Playlists page.
lang_play	User-defined name of the Play button column on the Playlists page.
lang_playall	User-defined text to display after the Play All button.
lang_playlists	User-defined text to display at the top of Playlists pages.
lang_search	User-defined text to display at the top of the Search page, and text to place in the Search button.
lang_searchresults	User-defined text to display at the top of the Search Results page.
lang_shuffle	User-defined name of the Shuffle button column on the Playlists page.
lang_various	User-defined artist name for albums containing songs by several artists.
lang_video	User-defined text to display on an Album Details page after the name of a video file. This makes it easier to distinguish between audio and video files.
lang_years	User-defined name of the Album Release Year index page.

The .install file

A skin is able to override user settings by including desired settings in a .install file in the skin folder. This file can also specify additional support files required by the skin Any file that ends in .install will be processed each time the skin files are copied to the output folder by Music Jukebox.

CONFIG Entries

If the .install file contains any CONFIG entries, Music Jukebox will set the specified configuration parameter to the value specified in the .install file. Each entry is specified like;

<CONFIG setting="albumlines" value="3" />

Valid parameters that can be overridden in the .install file are listed below.

Setting	Description	Allowed Values
AlbumCellHeight	Size, in pixels, of the table cell allocated to each album cover on an index page.	Number greater than 0.
AlbumLines	Number of lines of album covers on an index page.	Number greater than 0.
AlbumsPerLine	Number of album covers displayed on each line on an index page.	Number greater than 0.
AlbumSize	Size, in pixels, of an album cover image displayed on an album detail page.	Number greater than 0.
Apostrophe	Character to display instead of an apostrophe when an artist/genre/album/song contains an apostrophe.	Any Unicode character.
DolphMenu	Should Music Jukebox create a ‘popout’ menu?	‘True’ or ‘False’.
FocusHighlightColour	HTML colour name/number to use as the highlight around an album with the current focus.	Any valid HTML colour name or number. Precede numbers with ‘#’.
FocusTextColour	HTML colour name/number to use when text, such as genre name, is highlighted.	Any valid HTML colour name or number. Precede numbers with ‘#’.
HomePage	The URL to link the Home button to on the first page of the main index.	Any valid URL.
HTMLEncode	Should Music Jukebox encode text strings with proper HTML encoding.	True – Music Jukebox will do the encoding. False – Music Jukebox will leave the encoding up to the skin.
LargeButtonSize	Size, in pixels, of the navigation buttons.	Number greater than 0.
LocaImages	Should Music Jukebox copy album art images to the menu folder.	True – Images are copied to the menu folder and XML entries for images are filename only. False – XML entries for images include the path to the image.
MasterPlaylist	Should Music Jukebox create the master playlists.	‘True’ or ‘False’.
MaxSongLength	Maximum number of characters to display of a song name on the album detail pages. If the song name is longer than this value, it is truncated and ‘…’ is added. If this is set to 0, the full song name is used.	Number greater than or equal to 0.
MaxTextLength	Maximum number of characters to display of an artist name or album title on an index page. Longer names are truncated and ‘…’ is added. If this is set to 0, the full name is used.	Number greater than or equal to 0.
OffScreenScrolling	Should Music Jukebox generate HTML compatible with off-screen scrolling? Off-screen scrolling is commonly used for non-HD televisions.	‘True’ or ‘False’.
PartyMode	Should Music Jukebox create repeating shuffle playlist links?	‘True’ or ‘False’.
Shuffle	Should Music Jukebox create shuffle playlist links?	‘True’ or ‘False’.
SongSearch	Should Music Jukebox create a link to the Search page?	‘True’ or ‘False’.
SmallButtonSize	Size, in pixels, of the play buttons on an album detail page.	Number greater than 0.
SongsPerPage	Number of songs displayed on a single album detail page.	Number greater than 0.
ThumbnailSize	Size, in pixels, of an album cover displayed on an index page.	Number greater than 0.

INSTALL Entries

If the .install file contains any INCLUDE entries, Music Jukebox will copy each file specified by the entry to the menu (output folder) when the skin is selected. Each entry is specified like;

<INCLUDE>SomeFile.dat</INCLUDE>

If the entry does not include a complete path, Music Jukebox will assume the file is located in the skins folder. If the path is relative (does not start with a drive letter or backslash), Music Jukebox will use the skin folder as the starting point of the path. Each file will be copied to the menu folder, regardless of the path to the file being copied. You do not need to add any files located in a pictures subfolder of the skin. Music Jukebox will automatically copy these files, even if a .install file does not include them. Music Jukebox will also automatically copy all files with the following extensions from the skins folder to the menu folder, even if not specified in the .install file.

.css .htm .js .jsp .php