How to Write a musikCube Plugin

From Musik

Table of contents

1 Setting up Directory Structure 2 Compiling 3 musikWhat? 4 If you are writing a musikCube interface plugin: 5 If you are writing a musikPlayerPlugin (to extend file format support)

Setting up Directory Structure

I store all my source files in 'c:\source\' -- we will use this as the base directory in our example. You can use whatever directory you want, as long as the sub-directory has the following structure:

Directory	Description
c:\source\	root build directory
c:\source\musikCore	musikCore API
c:\source\musikCube	musikCube is the Windows GUI for musikCore
c:\source\musikPlugin	your plugin

Use CVS to obtain the latest versions of the source code. I recommend TortoiseCVS, which adds a CVS Checkout shell extension to Windows Explorer. See http://www.tortoisecvs.org/download.shtml. "Checkout" (download) the following modules: musikCore, musikCube, musikPlugin.

If you have TortoiseCVS do the following:

1. Go into Explorer and create a directory for the musik sources. Enter the directory and right click. From the popup menu select "CVS Checkout"
2. Use the following CVSROOT: :pserver:anonymous@musik.cvs.sourceforge.net:/cvsroot/musik . It should fill out all the information automatically, except for the module you want to check out.
3. For "Module" use musikCore. Press OK (To checkout all modules in CVS use a single dot, "." as the module)
4. After musikCore checks out, repeat the procedure for musikCube and musikPlugin (for musikCube plugins), or musikPlayerPlugin.

Compiling

Compiling your own musikPlugin is very easy. Find the file "musikPlugin.sln" in your musikPlugin source directory, and open it up with Visual Studio .NET. Once loaded, you should notice that building a musikPlugin will also build musikCore and musikCube for you automatically. You also have access to all the source files in both projects, amongst other projects (TagLib, OpenThreads, SQLite, and MMShellHook). You don't need to worry about anything but your musikPlugin workspace right now.

note: musikCore relies on the BASS Audio Library for audio playback. You need to download these libraries separately. Here is a direct link to the libraries we use and their respective readme's: http://musikcube.com/files/libs/bass_libs.zip. Extract *.dll to c:\source\musikCube\bin and *.lib to c:\source\musikCore\lib\ ... yes, this is a pain right now, sorry.

Press F5 to build everything.

Once everything is built, the fresh musikCube.will be launched, and your musikPlugin.dll will be loaded automatically. Congratulations, you have just compiled musikCore, musikCube and your new, empty plugin from scratch.

musikWhat?

musikPlugin depends on musikCube. musikCube depends on musikCore. This simple diagram may help.

If you are writing a musikCube interface plugin:

musikCube will automatically initialize the main musikCore::Library and musikCore::Player instances, and give you pointers to both them. Once your plugin starts up, it already has a valid handle to the active musikCore::Library and musikCore::Player used by the musikCube interface.

musikCube relies on musikCore, which is a database driven backend that has no ui specific code. Remember, musikCore is your friend when developing plugins because you have direct access to all the active musikCore objects in musikCube. Confused yet? Just remember these key objects that you have access to at any given time:

musikCore::Player: the class that musikCube uses to control playback. Start, stop, pause, resume, set and modify the "Now Playing" playlist, and more.

musikCore::Song: a single instance of a song as as queried from the database. The only thing this class actually contains is a "Song ID."

musikCore::SongInfo: the class that contains all the actual song information for a "Song ID." Artist, Album, Track No, Times Played, Last Played, Comments, notes, etc.

musikCore::Playlist: an array of musikCore::Song objects using std::vector. musikCore::Playlist is actually a std::vector<musikCore::Song>.

musikCore::Library: the SQL driven database. Use this to query information about songs.

Heres the breakdown: you query songs from a musikCore::Library -- typically to a musikCore::Playlist. Then you do something with the musikCore::Playlist: generate a report about songs, start playback, display... anything you could ever want to do to a group of songs.

For a basic, sample plugin, checkout the mcAmp source.

For a simple plugin using dialogs, checkout the WTL sample.

A copy of the musikCore SDK manual can be found here -- but you can always compile your own using Doxygen.

If you are writing a musikPlayerPlugin (to extend file format support)

musikCube will initialize the BASS soundsystem. Thats it. You need to implement the following function calls to assure your plugin works correctly:

bool CanPlay( const musikCore::String& filename );
bool Play( HSTREAM stream, int offset = 0 );
bool CanSeek();
bool Seek( HSTREAM stream, int ms );
bool Pause( HSTREAM stream );
bool Resume( HSTREAM stream );
bool Stop( HSTREAM stream );
int GetDuration( HSTREAM stream );
int GetTime( HSTREAM stream );
bool IsActive( HSTREAM stream );
HSTREAM LoadFile( const musikCore::String& file );
bool WriteTag( const musikCore::SongInfo& info );
bool ReadTag( const musikCore::String& fn, musikCore::SongInfo& target );

Note: some of these functions may have a default implementation that should work, but feel free to change them if necessary. The BASS documentation will prove to be very useful during development, as it already does most of the dirty work for you. Please be sure to check the core_APE example plugin that implements the Monkey Audio APE format.

If you have any additional comments or questions, don't hesitate to stop by our message board.

There is a short step-by-step introduction of how to write an input plugin by otto in the forums: see [1] (http://musikcube.com/punbb/viewtopic.php?pid=3619#p3619)