Media Jukebox Interface SDK (automation)
(last updated August 22, 2002)
(required Media Jukebox 8.0.320 or later)

Introduction

Media Jukebox exports much of its power and functionality through COM automation interfaces.  This makes it easy to create your own plug-ins for Media Jukebox that integrate tightly with its interface.  Since everything is based around COM, these plug-ins can be written in almost any language. (C++, VB, Delphi, etc.). Also, the interfaces can be accessed in Metamorphis skins and Display plug-ins (see documentation for the plug-ins)

Interfaces

Contents:

CMJAutomation - core object... provides access to all other objects
CMJPlaybackAutomation - controls playback and provides information about the currently playing track
CMJFilesAutomation - represents a collection of files
CMJFileAutomation - object for dealing with a single file
CMJCurPlaylistAutomation - interface for working with "Playing Now" (the current playlist)
CMJMixerAutomation - provides volume, balance, and mute control
CMJPlaylistsAutomation - represents a collection of playlists
CMJPlaylistAutomation - interface for working with a single playlist
CMJSchemeAutomation - interface for working with Media Library
CMJVersionAutomation - interface for getting Media Jukebox version information
CMJInternetAutomation - interface for helping in downloading files from internet

CMJAutomation - core object... provides access to all other objects

Functions

CMJPlayback * GetPlayback()

Description: gets a CMJPlayback interface (see below)
Return Value: CMJPlayback interface

CMJFilesAutomation * Search(string strSearch)

Description: gets a CMJFilesAutomation interface (see below) for the files matching the specified search
Parameters:

strSearch: the search string to use... can be any search accepted by Media Jukebox

Return Value: CMJFilesAutomation interface

CMJCurPlaylistAutomation * GetCurPlaylist()

Description: gets a CMJCurPlaylistAutomation interface (see below)
Return Value: CMJCurPlaylistAutomation interface

CMJPlaylistsAutomation * GetPlaylists()

Description: gets a CMJPlaylistsAutomation interface (see below) for all of the existing playlists
Return Value: CMJPlaylistsAutomation interface

CMJSchemeAutomation * GetViewScheme(string strPath)

Description: gets a CMJSchemeAutomation interface (see below) for the given library path 
Parameters:

strPath: the path to the view scheme delimited by backslashes. (i.e. "Media Library\Artist/Album\Metallica")

Return Value: CMJSchemeAutomation interface

CMJInternetAutomation * GetInternet()

Description: gets a CMJInternetAutomation interface (see below).
Return Value: CMJInternetAutomation interface

CMJMixerAutomation * GetMJMixer()

Description: gets a CMJMixerAutomation interface (see below)
Return Value: CMJMixerAutomationinterface

CMJVersionAutomation * GetVersion()

Description: gets a CMJVersionAutomation interface (see below).
Return Value: CMJVersionAutomation interface

CMJFileAutomation * GetFile(string strFilename)

Description: gets a CMJFileAutomation interface (see below) for the given file.
Parameters:

strFilename: the path to the file.

Return Value: CMJFileAutomation interface

void EnableSkinning(number bEnable)

Description: Enables and disabled Media Jukebox skinning. Useful in case when MJ could not skin plug-in window correctly.
Parameters:

bEnable: TRUE - enable skinning, FALSE - disable.

number GetSkinInfo(string strItem, string strAttribute)

Description: Retrieves information about current skin.
Parameters:

strItem: item name.
strAttribute: attribute name.

Return Value: value of the specified skin item. -1 if the info was not found.

Example1: GetSkinInfo("Tree", "TextColor");
Example2: GetSkinInfo("StatusBar", "BackColor");

number IsPurchased()  (added in v8.0.354)

Description: Retrieves registration information

Return Value: if Media Jukebox is purchased return value will be -1. The value will be equal to 0 if trial period expired but the program was not purchased.  If the value > 0 the function returned number of days left in the trial period.

CMJPlaybackAutomation - controls playback and provides information about the currently playing track

Functions

void Pause()

Description: toggles the pause state

void Stop()

Description: stops playback

void Next()

Description: plays the next track in "Playing Now"

void Previous()

Description: plays the previous track in "Playing Now"

void FastForward()

Description: advances the position of the playing track (amount depends on file type)

void Rewind()

Description: rewinds the position of the playing track (amount depends on file type)

boolean IsBuffering()

Description: queries to see if Media Jukebox is buffering
Return Value: TRUE if buffering, FALSE if not buffering

void Play()

Description: begins playback of the current track in "Playing Now"

boolean IsVideo()

Description: queries to see if Media Jukebox has video
Return Value: TRUE if MJ has video, FALSE if not.

Properties

MJPlaybackStates State() (read only)

Description: the current playback state (PLAYSTATE_STOPPED - Stopped, PLAYSTATE_PAUSED - Paused, PLAYSTATE_PLAYING -  Playing, PLAYSTATE_WAITING - Waiting)

number Bitrate() (read only)

Description: the bitrate of the currently playing track (i.e. 128 kbps)

number Position() (read / write)

Description: the position in the currently playing track (i.e. 111 seconds)

number Duration() (read only)

Description: the duration of the currently playing track (i.e. 257 seconds)

number Channels() (read only)

Description: the number of channels in the currently playing track (i.e. 2 channels (stereo))

number Samplerate() (read only)

Description: the sample rate of the currently playing track (i.e. 44100 Hz)

number Bitspersample() (read only)

Description: the bits per sample of the currently playing track (i.e. 16 bits per sample)

CMJFilesAutomation - represents a collection of files

Functions

number GetNumberFiles()

Description: returns the number of files contained in the collection
Return Value: number of files

void Sort()

Description: sorts the list of files using user selected sorting scheme.

CMJFileAutomation * GetFile(number nFile)

Description: gets the CMJFileAutomation interface (see below) for the given file index
Parameters:

nFile: the index of the file to retrieve (0 to GetNumberFiles() - 1)

Return Value: CMJFileAutomation interface

CMJFileAutomation - object for dealing with a single file

Functions

CMJPlaylistsAutomation * GetPlaylists()

Description: returns the collection of playlists that the given file is in
Return Value: CMJPlaylistsAutomation interface (see below)

string GetImageFile(MJImageFileFlags nImageFileFlag)

Description: gets the filename of an image associated with the file
Parameters:

nImageFileFlag: IMAGEFILE_DISPLAY -  display image (uses MJ logo if file doesn't have an image), IMAGEFILE_IN_DATABASE - database image, IMAGEFILE_IN_FILE - tag image (stored inside of file)

Return Value: a filename of the image file

string SetImageFile(string strImageFile, MJImageFileFlags nImageFileFlag)

Description: sets the image for the file
Parameters:

strImageFile: filename of the image
nImageFileFlag:
IMAGEFILE_IN_DATABASE - database image, IMAGEFILE_IN_FILE - tag image (stored inside of file)

Return Value: 0 on failure, non-zero on success

string GetFormattedFileSize()

Description: gets the display friendly file size
Return Value: a string representing the file size (i.e. "23.434 MB")

string GetFormattedFileDate()

Description: gets the display friendly file date / time
Return Value: a string representing the file date / time (i.e. "2/30/2002 8:01 PM")

string GetFormattedDuration()

Description: gets the display friendly duration
Return Value: a string representing the duration (i.e. "3:04")

string GetFormattedLastPlayed()

Description: gets the display friendly last played date / time
Return Value: a string representing the duration (i.e. "2/30/2002 8:01 PM")

string GetAvailableFilename()

Description: returns the filename in the format that's available to the system, so that files on a removable device get returned, for example, as "D:\1.mp3" instead of "(0xF43EA231):\1.mp3"
Return Value: a string representing the filename

boolean SaveToTag()   (added in v8.0.354)

Description: Forces Media Jukebox to save the file information to the tag.
Return Value: 0 - failed, 1 - success.

Properties

string Filename() (read / write)

Description: the filename (i.e. "c:\Music\Good Song.mp3")

string Artist() (read / write)

Description: the artist (i.e. "Metallica")

string Album() (read / write)

Description: the album (i.e. "ReLoad")

string Name() (read / write)

Description: the name of the track (i.e. "Unforgiven II")

number Filesize() (read / write)

Description: the filesize in bytes

number Duration() (read / write)

Description: the file duration in seconds

string Genre() (read / write)

Description: the genre (i.e. "Rock")

number Year() (read / write)

Description: the year (i.e. 1997)

string Comment() (read / write)

Description: the comment

number Bitrate() (read / write)

Description: the bitrate (i.e. 128 kbps)

number Tracknumber() (read / write)

Description: the track number (i.e. 4)

number Filedate() (read / write)

Description: the file's date (seconds past 1970)

string Custom1() (read / write)

Description: the MJ-specific "Custom 1" field

string Custom2() (read / write)

Description: the MJ-specific "Custom 2" field

string Custom3() (read / write)

Description: the MJ-specific "Custom 3" field

number PlayCounter() (read / write)

Description: the number of times the track has been played in Media Jukebox

number LastPlayed() (read / write)

Description: the date the file was last played in Media Jukebox (seconds past 1970)

number Rating() (read / write)

Description: the rating (MJ-specific) (note: 0 = ?, otherwise 1-5)

string Filetype() (read / write)

Description: the extension of the file (used by MJ to choose playback plugins, etc.) (i.e. "mp3")

string Lyrics() (read / write)

Description: the lyrics

string Notes() (read / write)

Description: the notes

CMJCurPlaylistAutomation - interface for working with "Playing Now" (the current playlist)

Functions

number GetNumberFiles()

Description: returns the number of files in "Playing Now"
Return Value: number of files

CMJFileAutomation * GetFile(number nFile)

Description: gets the CMJFileAutomation interface (see below) for the given file index
Parameters:

nFile: the index of the file to retrieve (0 to GetNumberFiles() - 1)

Return Value: CMJFileAutomation interface

void RemoveAllFiles()

Description: removes all of the files from "Playing Now" (stops playback)

boolean RemoveFile(number nFile)

Description: removes a specific file from "Playing Now"
Parameters:

nFile: the index of the file to retrieve (0 to GetNumberFiles() - 1)

Return Value: 0 on failure, non-zero on success

boolean AddFile(string strFilename, number nPosition)

Description: adds a file to "Playing Now"
Parameters:

strFilename: the filename of the file to add
nFile:
the new index of the file

Return Value: 0 on failure, non-zero on success

boolean MoveFile(number nFileOld, number nFileNew)

Description: moves a file to a new location in "Playing Now"
Parameters:

nFileOld: the index of the file to move 
nFileNew:
the index to move the file to

Return Value: 0 on failure, non-zero on success

boolean ReShuffleFiles()

Description: shuffles "Playing Now" so it's in a random order
Return Value: 0 on failure, non-zero on success

number GetNextFile()

Description: gets the index of the file to play on "Next"
Return Value: index of file

boolean GetPreviousFile()

Description: gets the index of the file to play on "Previous"
Return Value: index of file

Properties

number Position() (read / write)

Description: the index of the current track

number Shuffle() (read / write)

Description: the shuffle state (0 = off, 1 = on)

number Continuous() (read / write)

Description: the continuous state (0 = off, 1 = on)

CMJMixerAutomation - provides volume, balance, and mute control

Functions

void SetEQBand(number nBand, number nValue)

Description: sets the value of an equalizer band
Parameters:

nBand: the equalizer band (0 = preamp, 1 - 10 = eq bands)
nValue: the new band value (-100 to 100 where -100 is full cut, 0 is no gain, and 100 is full gain)

number GetEQBand(number nBand)

Description: gets the value of an equalizer band
Parameters:

nBand: the equalizer band (0 = preamp, 1 - 10 = eq bands)

Return Value: value of the specified band (-100 to 100 where -100 is full cut, 0 is no gain, and 100 is full gain)

Properties

number Volume() (read / write)

Description: the volume (0 = no volume, 100 = full volume)

number Balance() (read / write)

Description: the balance between left and right (-100 = all left, 0 = centered, 100 = all right)

boolean Mute() (read / write)

Description: the mute state (0 = not muted, 1 = muted)

boolean EQOn() (read / write)

Description: whether the equalizer is on or off (0 = off, 1 = on)

 

CMJPlaylistsAutomation - represents a collection of playlists

Functions

number GetNumberPlaylists()

Description: returns the number of playlists contained in the collection
Return Value: number of playlists

CMJPlaylistAutomation * GetPlaylist(number nPlaylist)

Description: gets the CMJPlaylistAutomation interface (see below) for the given playlist index
Parameters:

nPlaylist: the index of the playlist to retrieve (0 to GetNumberPlaylists() - 1). To retrieve Top Hits and Recently Imported playlists use index -1 and -2 respectively.

Return Value: CMJPlaylistAutomation interface

CMJPlaylistAutomation * CreatePlaylist(string PlaylistPath, string PlaylistName)

Description: Creates new playlist at the specified location (added in v8.0.340)
Parameters:

PlaylistPath: location of the playlist. If empty, the playlist will be created in the root of the playlist tree.
PlaylistName:
name of the new playlist

Return Value: CMJPlaylistAutomation interface

boolean DeletePlaylist(string PlaylistPath, string PlaylistName)

Description: Deletes existing playlist (added in v8.0.340)
Parameters:

PlaylistPath: location of the playlist.
PlaylistName:
name of the new playlist

Return Value: true - if success, otherwise false.

CMJPlaylistAutomation - interface for working with a single playlist

Functions

CMJFilesAutomation * GetFiles()

Description: gets the collection of files in the playlist
Return Value: CMJFilesAutomation interface

boolean AddFile(string strFilename, number nLocation)

Description: adds new file to the playlist (added in v8.0.340)
Parameters:

strFilename: the filename of the file to add
nLocation: position of the file in the playlist. If position -1, the file will be added to the end of the playlist.

Return Value: 0 on failure, non-zero on success

boolean RemoveFile(string strFilename)

Description: removes existing file from the playlist (added in v8.0.340)
Parameters:

strFilename: the filename of the file to delete

Return Value: 0 on failure, non-zero on success

Properties

string Name() (read / write)

Description: the name of the playlist (i.e. "My Playlist")

string Path() (read / write)

Description: the path of the playlist, delimited by backslashes (note: does not contain the name) (i.e. "Mixes\\New Playlist Group")

CMJSchemeAutomation - interface for working with Media Library

Functions

string GetName()

Description: gets the name of the scheme item (i.e. "Classic Rock", "Artist\Album", etc.)
Return Value: a string containing the name of the scheme item

number GetNumberSchemes()

Description: gets the number of children schemes
Return Value: number of children schemes

CMJSchemeAutomation * GetScheme(number nScheme)

Description: gets the specified child scheme
Parameters:

nScheme: the index of the child scheme to retrieve (0 to GetNumberSchemes() - 1)

Return Value: a CMJSchemeAutomation interface for the specified child scheme

CMJFilesAutomation * GetFiles()

Description: gets the collection of files in the scheme
Return Value: CMJFilesAutomation interface of files

string GetSchemeName(number nScheme)

Description: gets the name of the specified child scheme (faster than GetScheme(...))
Parameters:

nScheme: the index of the child scheme to retrieve (0 to GetNumberSchemes() - 1)

Return Value: a string containing the name of the child scheme item

CMJVersionAutomation - interface for getting Media Jukebox version information

Properties

number Major (read only)

Description: Major version of the Media Jukebox (i.e. 8)

number Minor (read only)

Description: Minor Version of the Media Jukebox  (i.e. 0)

number Build (read only)

Description: Build number of the Media Jukebox (i.e. 234)

string Version (read only)

Description: string version of the Media Jukebox (i.e. "8.0.234")

CMJInternetAutomation - interface for helping in downloading files from internet

Properties

MJInetDownloadModes DownloadMode (read / write)

Description: Gets or sets download mode.

DOWNLOAD_MODE_DEFAULT - displays UI while downloading files from the Internet
DOWNLOADMODE_NO_UI - does not display UI but processes the message loop so the Cancel function can be called from the same thread.
DOWNLOADMODE_BLOCKING - will lock the app until the download is finished.
DOWNLOAD_MODE_NO_AUTHENTICATION - disables authentication.

Example1: MJIA.DownloadMode = DOWNLOADMODE_NO_UI | DOWNLOADMODE_BLOCKING;

Functions

string DownloadToString(string URL)

Description: Downloads web page from the specified URL to a string. (should not be used with binary data, only web pages)
Parameters:

URL: The URL from which the web page will be downloaded.

Return Value: a string containing the contents of the web page.

number DownloadToFile(string URL, string FileName)

Description: Downloads data from a resource identified by a URL to a local file.
Parameters:

URL: The URL from which the data will be downloaded.
FileName: The name of the local file to receive the data.

Return Value: True if the function completed successfully, otherwise FALSE.

string DownloadToTempFile(string URL)

Description: Downloads data from a resource identified by a URL to a local temp file.
Parameters:

URL: The URL from which the data will be downloaded.

Return Value: Returns the full path to the temp file.

void Cancel()

Description: Cancels previously called download function. Can be used only when DownloadMode set to DOWNLOADMODE_NO_UI or DOWNLOADMODE_NO_UI_BLOCKING.

Support

If you have questions or concerns not addressed by this SDK, or just have suggestions for making the SDK more understandable, please visit our developer's forum