Music Miner
Home
About
Download
Documentation
Sounds
Contact

Music Miner: Documentation

  1. Requirements
  2. Installation
  3. Linking
  4. Using
  5. API

1. Requirements

To use the music miner you (probably) need Linux or some other UNIX based OS. Although most of the code should work on windows as well. The "greatest" portability program is the directory where created wav files are created. This is always in the user's home dir (~). Other than that, ANSI C is used pretty much anywhere, although I haven't tested it yet. Porting it to a non-UNIX like operating system is something you'll have to do yourself.

That said, you don't need anything else, except for some source code of a program you want to play with. Which means you DO need a C compiler.

2. Installation

You must download the music miner source code and untar it to a directory somewhere. Then you can run the ./configure && make , su, make install routine:

This will install 3 files. First the library itself, libmusicminer.a, is placed in your main lib directory (e.g. /usr/lib).
Secondly a directory, music_miner, is created in your main include directory (e.g. /usr/include) and the C header files wav_writer.h and music_miner.h are copied to that directory. The header file music_miner.h is the most important header file, it declares the API you'll be using. The header file wav_writer.h shouldn't be included anywhere by you (music_miner.h does that for you).

3. Linking

If you have a program compiling with gcc than you can link the static music miner library to it. If you've installed the library to a default library directory then you can just add the option -lmusicminer to the gcc command compiling the program. Otherwise you should use the -L option to add the directory where you installed the library.

In every decent open source project there is a Makefile and a configure file etc. You should edit those files. Preferably you edit the configure.in or makefile.am files, then use autoconf and automake to regenerate the makefile.in and the configure script and then run configure again. How this works pretty much depends from project to project (as far as I know). You should be able to find it though.

If you don't know anything about automake and autoconf and how they work together, there are a some good tutorials out there.

4. Using

So... you have a program and you seem to have linked the library to it. But the program isn't making sound allready. You have to specify what will be written to which wav file, and how it should be written.

To use the functions somewhere you should first #include <music_miner/music_miner.h>.

To identify the wav files created by the music miner you specify a file prefix when you initialize the library. Every run of your edited program a new file is created starting with the prefix a number and the .wav extension. The wav files are placed in the directory ~/.music_miner. The number is incremented each time a new file is created, it can count to 9999... and then, well, something happens but I'm not sure what.

Say you specify the prefix "test" and run some program twice, you get two files named test0000.wav and test0001.wav.

To initialize the music miner you can use mm_load_music_miner();. This functions takes three arguments: the filename prefix, the samplerate and the bits per sample of the wav file. So before you can start making a 44100 Hz, 16-bit wav file with the "test" prefix you do this once somewhere in your code (best in main):
mm_load_music_miner("test", 44100, 16);

Now say the program you're editing has a function void write_preferences(struct pref * prefs); and you want to use the prefs structure as wav data every time the write_preferences(); function is called. Then you must add a call to the mm_write(); function. This function takes two arguments. A pointer to the data to be written and a length value indicating the length of the data in bytes. You might use this code: 

void write_preferences(struct pref * prefs) {
  ...
  mm_write(prefs, sizeof(struct pref));
  ...
}

Compile and run that program and you should have a wav file, with some data if the write_preferences(); function was indeed called. It's ready for a life as a sound sample. Or, maybe, a piece of music?

5. API

This API consists only of the "public" functions and structure.

mm_load_music_miner

mm_global_info * mm_load_music_miner(char * filename_prefix, unsigned short samplerate, unsigned short bits_per_sample);

Fills the global structure with all the necesarry info.

mm_get_global_info_structure

mm_global_info * mm_get_global_info_structure();

mm_write

void mm_write(void * data, int length);

Will write length amount of bytes to the wav file (as wav data), starting from the data pointer.

mm_write_repeat

void mm_write_repeat(void * data, int length, int count);

Will write length amount of bytes to the wav file (as wav data), starting from the data pointer and repeat it for "count" times.

structure: mm_global_info

typedef struct {
  char * filename;

  mm_format_chunk * format_chunk;
  mm_data_chunk * data_chunk;
  mm_wave_header * ;

  long header_start;
  long data_start;
} mm_global_info;

You probably don't want to use this structure. But it's here because you ARE allowed to get at it. Most of the fields (except for the filename) are concerned with the wave file formatting.