C++ library and programs for processing Humdrum data files.
To download from a terminal if you have git installed on your system:
git clone https://github.com/craigsapp/humextra
Otherwise you can download from the "zip" link at the top of this page
(https://github.com/craigsapp/humextra/archive/master.zip). From the
command line you can download the humextra ZIP file with this command
in linux:
wget https://github.com/craigsapp/humextra/archive/master.zip
or use curl in OS X:
curl -L https://github.com/craigsapp/humextra/archive/master.zip > master.zip
Then unzip the file with this command:
unzip master.zip
If you want to use the "git" command to download the humextra software,
check to see if it is installed on your computer by typing this command
in the terminal:
which git
It should return with the location of the command in the file structure,
such as:
/usr/bin/git
If which git does not reply with any location, then you will have to
install git. There are several ways to install it:
(1) In linux/unix, use some automated installation system which is
installed on your computer. Some possible methods: yum install git,
apt-get install git (Ubuntu), or emerge git (Gentoo).
(2) in OS X, use a package management system such as Homebrew
(http://mxcl.github.io/homebrew) or MacPorts (http://macports.org).
For example, to install Homebrew type the following command in the
terminal:
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
Homebrew and MacPorts are two OS X equivalents of apt-get/yum/emerge
which are used to install software over the internet on linux systems.
In Mac OS X 10.9 (Mavericks) you should first install the Xcode
command-line compiling tools using this command:
xcode-select --install
This will install xcode command-line tools over the internet after you
click on a few pop-up windows.
For older Mac OS X versions, you will need to first install XCode from the Apple App Store (free). After installing XCode, go into its menu system and install the command-line development tools: (a) click on the Downloads tab in XCode (b) select "command line tools" (c) click on "install" button.
To install git after homebrew/macports and XCode command line tools are
installed. type brew install git if using Homebrew, or sudo port install git if using MacPorts.
IDEs such as Eclipse (http://www.eclipse.org/downloads) have a git interface built into them. Other GUI-based git programs can be found at this link: http://git-scm.com/downloads/guis . These might be more appropriate for MS Windows, although you will have to install a unix terminal system such as cygwin (http://www.cygwin.com) to use the humextras program in MS Windows.
To compile everything, type within the main humextra directory:
make
If using OS X, see the above notes on XCode in the Download section if you get a
complaint about the make command not being found.
To compile only the humextra library:
make library
To compile all humextra programs (after making the library):
make programs
To compile a particular humextra program (after making the library):
make humcat
To test that the programs have been compiled successfully, try typing:
bin/keycor h://wtc/wtc1f01.krn
which should reply with an estimate of the key for J.S. Bach's Well-Tempered Clavier,
Book I fugue 1:
The best key is: C Major
Compiled programs will be stored in the humextra/bin sub-directory.
To use these programs from any location in the file system, you must tell
the computer where to search for them. This is done in the terminal by
adding the bin directory to the $PATH variable. Type echo $PATH
to see what directories are currently being searched for commands.
A lazy way of installing would be to copy the programs in humextra/bin
into one of those locations, such as /usr/bin.
A more proper way would be to update the $PATH environmental variable.
To do this you will need to know which shell you are using. Type echo $SHELL in the terminal to see which one: bash or tcsh are the two main
ones. If you are using bash, then you can temporarily add humextra/bin
to the $PATH with this command:
PATH=$PATH:/location/of/humextra/bin
To do the same in tcsh (without the outer set of quotes):
setenv PATH $PATH":/location/of/humextra/bin"
For a more permanent installation the $PATH must be updated in the login
scripts for bash/tcsh, either for a single user or for the entire system.
For an individual user in bash add this line:
export PATH=$PATH:/location/of/humextra/bin
to the file ~/.bashrc . For tcsh, add the line
setenv PATH $PATH":/location/of/humextra/bin
to the file ~/.csrhc . Alternatively, the PATH environmental variable
may need to be set in ~/.profile.If you want to install for all users
on a computer system then you would add such lines to the system login
script (which will vary on the version of unix you are using).
Most command-line tools from Humdrum Extras can be run online from this page. These online versions of the programs were compiled with Emscripten into JavaScript and run directly in your browser. Here are some of the online version of the humextra tools:
barnum, beat, blank, cint, dittox, extractx, gettime, harm2kern, hgrep, hum2xml, humcat, humtable, keycor, location, minrhy, mvspine, myank, pitchmix, prange, prettystar, ridx, rscale, runningkey, sample, satb2gs, scaletype, scordur, serialize, thrux, tntype, transpose, voicecount.
To update if you downloaded with git:
git pull
Then either type make to recompile the external libraries, the humextra
library and the programs, or type make update to compile just the humextra
library and programs, or make libupdate to update only the library file
without recompiling example programs. If you installed by download a ZIP file,
then you would need to re-download another ZIP file with the updated code.
When using git to download and update the humextra repository, you can add these lines to ~/.gitconfig:
[alias]
hist = log --pretty=format:\"%h %ad | %s%d [%an]\" --graph --date=short
Then the command git hist will give a short listing of changes (one commit per line)
sorted in reverse chronological order.
All humextra programs include an option called --options which will list
all of the defined options for the program along with their aliases and default values.
For example here is the options list for the barnum program:
barnum --options
r|remove=b
s|start=i:1
a|all=b
debug=b
author=b
version=b
example=b
h|help=b
The line r|remove=b means that the barnum program accepts an option
called -r or equivalently --remove which is a Boolean type of option
(it does not take arguments, but is rather a switch to turn on a feature
in the program). The line s|start=i:1 means that the -s or --start
option requires an integer argument, and the default value if not given
is the value 1. Options can also have types d for double arguments
(floating-point numbers) and s for string arguments.
For more detailed information about each humextra program, go to the webpage http://extras.humdrum.org/man or click on the command name in the list below:
addref, autodynam, autostem, barnum, beat, chorck, cint, dittox, extractx, gettime, harm2kern, hgrep, hum2abc, hum2gmn, hum2mid, hum2muse, hum2xml, humcat, humpdf, humplay, humsplit, humtable, kern2cmn, kern2dm, kern2melisma, kern2skini, keycor, location, lofcog, mid2hum, minrhy, mkeyscape, motive, mvspine, myank, notearray, ottava, pae2kern, pitchmix, prange, prettystar, proll, rcheck, ridx, rscale, sample, satb2gs, scaletype, scordur, serialize, simil, similx, sonority, spinetrace, swing, theloc, themax, thememakerx, thrux, tiefix, time2matlab, time2tempo, tindex, tntype, transpose, tsroot, voicecount, xml2hum, zscores.
For a basic tutorial on programming with the humextra library, see the webpage http://wiki.ccarh.org/wiki/Humdrum_Extras .