bspaans / cmingus Goto Github PK

================================================================================
				    CMINGUS
================================================================================

  cmingus is a low priority implementation of the Python music library mingus 
  in C and C++. 

================================================================================
				      WHY?
================================================================================

  * For speed

    Simple structs and macros greatly reduce the amount of work the cpu has 
    to do. Add this to the natural advantage of compiling to machine code
    and you have got yourself a tiny, super fast music (theory) library.
    I'll upload some benchmarks to my site later, showing speed-ups of at 
    least 5000%. These speed differences will only get bigger once we get to 
    the more complicated functionality (recognising complex chords and 
    harmonic functions) which build on the simpler stuff (recognizing 
    intervals). Thus it will be better suited for analytical and real-time 
    applications (as part of a pipeline, for instance).

  * Cross Compilation

    Distributing Python code and letting the users/packagers figure out the 
    dependencies is not the most friendly thing to do, especially not for
    Windows users. For Python there is `freeze` to turn your applications into
    windows executables, but it would mean heaving to spend time with `freeze`
    when you want everything to just work on every platform. The automake tools
    can deal with that much better.

  * Compatibility

    Most programs using mingus involve the FluidSynth bindings in some way.
    When using C and C++ we can use the API directly and also incorporate
    other programs/libraries without having to write or adjust the Python 
    bindings. Most audio software is written in C/C++ so this should be 
    a time saver.

  * Fun

    Since the python implementation of mingus.core and mingus.containers is 
    pretty solid at this point, I started this experiment to see if the base 
    could easily be transfered to other languages and how much it would benefit
    from that. I also wanted some more experience with C and C++.

    The result so far is a lot less Pythonic in the core (obviously), but also 
    very much like the original version. The biggest difference is that notes, 
    intervals and chords aren't strings anymore, but structs which can be
    converted to and from strings instead. Apart from that; the API is very 
    similar to the original and also -rather surprisingly- doesn't defer much in 
    line count.

================================================================================
				   RESOURCES
================================================================================

  [1] The mingus homepage
      http://mingus.googlecode.com
  [2] The cmingus git repository
      http://github.com/bspaans/cmingus/

================================================================================
				     GOALS
================================================================================

  * Test-driven (currently >40 tests)
  * Cross platform (compiling with gcc and mingw)
  * Implement from mingus.core: notes, diatonic, intervals (90% DONE), meter 
    value, chords (40% DONE) and progressions (0% DONE)
  * Implement remaining base features of mingus.core (OPTIONAL)
  * Implement from mingus.containers (in c++): Note (70% DONE), NoteContainer
    (40% DONE), Bar (10% DONE), Track (5% DONE)
  * Link fluidsynth and play a note (DONE).

================================================================================
				    FEATURES
================================================================================

  mingus.core (in C):

  * Structures for notes, intervals, chords and progressions.
  * Augment and diminish notes and convert them to and from integers.
  * Get the diatonic scale in every conceivable key.
  * Create intervals absolutely or diatonically.
  * Create chords absolutely, diatonically or by harmonic function (currently 
    supported: triads and sevenths)
  * Recognize intervals between notes and produces theoretically sound names 
    for them.
  * Recognize all the different triads; naming them in the traditional 
    convention or in a 'jazzy' shorthand.

  mingus.containers (in C++):

  * Datastructures for storing and working with Notes, Chords, Bars and Tracks.

  mingus.midi (in C++):

  * Link FluidSynth and play a Note.

================================================================================
				  INSTALLATION
================================================================================

  Installing is done using ./configure and make. See INSTALL for more 
  information. You'll need the fluidsynth library (ie. libfluidsynth) to 
  compile.

    $ ./configure CFLAGS="-O3" && make

  This will build the mingus unit tests binaries and libraries. The 
  executables will test all the known functions when run. It aborts when 
  it encounters a false test-case, but this normally shouldn't happen since
  everything in the repository should build and work properly.

================================================================================
				    LICENSE
================================================================================
    
  cmingus, a reimplementation of mingus in C.
  Copyright (C) 2008, Bart Spaans <[email protected]>

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.

================================================================================