Csndshell

Introduction

Understanding the Config File

Installation

Using Csndshell

Common Problems

Introduction

The purpose of Csndshell is to combine Ascore and Mscore into a unified MIDI scoring program. The csndshell.sh file is a Unix shell script written in the Bash command syntax. It runs all the Ascore and Mscore scripts necessary for converting an Ascore music score file into a binary, operating system independent MIDI file (SMF).

Understanding the Config File

The csndshell.sh script requires a config file to run. Although the primary purpose of Csndshell is to "connect" Ascore with Mscore, the script was embedded with hooks for future expansion. Think of the config file as like a set of "patch cables" that routes the data processing between appropriate modules of a synthesizer. At present, there is only one valid "connection path" for the script, i.e., between Ascore and Mscore. But the connection statements are necessary in the config file anyway.

                            ---------------
                            |             |
                            |   Ascore    |
                            |   script    |
                            |             |
                            ---------------
                              <ascore.awk>
                                  |
                                  |
                                  |
           ------------<---- Csound Score ------>-----------
           |                      |                        |
           |                      |                        |
     <cs2mtx.awk>                 |                     <csound>
   ----------------               |               -------------------
   |              |               |               |                 |
   |  MTX         |                               |     WAV file    |
   |  score       |                               |                 |
   |              |                               -------------------
   ----------------                                        |
           |                                               |
           |                                               |
     <mscore.awk>                                          |
   ----------------                                        |
   |              |                                        |
   |  MIDI        |                                        |
   |  file        |                                        |
   |              |                                        |
   ----------------                                        |
           |                                               |
           |                                               |
   ----------------  ----------------                      |
   |              |  |     or       |                      |
   | Pmidi        |  |  remote PC   |                      |
   | midi to instr|  |    running   |                      |
   |              |  |   Pmidi      |                      |
   ----------------  ----------------                      |
           |                |                              |
           |  <-------------|                              |
           |                                               |
       PC  | connected to synthesizer                      |
           |                                               |
    --------------                                         |
    |    Your    |                                         |
    | Synthesizer|                                         |
    --------------                                         |
           |                                               |
           | audio                                         |
           |                                               |
   ----------------                                        |
   |              |                                        |
   |  Record      |                                        |
   |  to  WAV     |                                        |
   |              |                                        |
   ----------------                                        |
           |                                               |
           |                                               |
   ----------------                                        |
   |              |                                        |
   |   WAV file   |                                        |
   |              |                                        |
   ----------------                                        |
           |                                               |
           |                                               |
           |                                               |
           -----------------------|-------------------------
                                  |
                                  |

                

The following statements are needed in the config file:

1. The Ascore file. This is your score file. This statement must be of the form

   ascore=filename

2. Route the score to the first processor, that is, the Score Node. The statement must be of the form

   node_score=next_module

   At present, there is only one valid choice for the next module, and that is the Csound-to-Mtx code. So, the Score Node command must look like

   node_score=MTX

3. Route the Mtx-formatted file to the next processor. The Mtx file is MIDI data represented by a pseudo language called MTX script. The natural next step would be to convert it into an SMF binary file (a MIDI file). The Mtx Node statement of the form

   node_mtx=next_module

   should be given with the only currently-available path selection,

   node_mtx=MIDI

4. Route the MIDI file. Should we copy or play the output MIDI file? Currently, the only valid path here is to copy the MIDI file to a remote PC (the sequencer PC). If there is no remote PC then this statement is omitted (and processing is stopped). The MIDI node statement should be the RMIDI (remote midi) node

   node_midi=RMIDI

   or omitted if there is no remote computer.

5. The following statements are options in the config file:
   
   csound=[yes,no]

   Run Csound if it is installed on your computer. This option was tailored for running a specific version of Csound. If your target is Csound you don't need Csndshell, anyway--just run Ascore and use its output for Csound. For MIDI output it is safe to put no here.

   
   expect_rmidi=[yes,no]

   Use the Expect script for automatically copying the MIDI file using SSH. This option is only used for copying the output MIDI file to a remote computer. Put no if there is no remote computer.

   
   post_mtx=[yes,no]

   Whether to run the post_cs2mtx script before converting to an SMF. For creating a MIDI file output this statement is required, so put yes.

Installation

Installation is basically nothing more than unpacking the files. You can run the install.sh script that will be unpacked with the project, but this is optional. The purpose of the install script is to set environment variables in your /etc/profile file (Csndshell must use the Bash shell). These environment variables are set only for the convenience of easily running Csndshell. Instead of typing the full path to the script file, you can use the environment variable. If you know what you're doing you can just edit your local .bashrc file and insert the environment variables.

If you decide not to run the install.sh script, then you can start the csndshell.sh script by manually typing the full path every time, like this

/usr/local/share/csndshell/csndshell-1.0.1/csndshell.sh my_config.conf

which is just the path to the script and the name of the config file (located in the working directory).

Using Csndshell

You use csndshell.sh to convert your Ascore file into a MIDI file. For using Ascore, see the Ascore HOWTO:

http://www.lumanmagnum.net/physics/ascore/index.html

Verify that your config file for Csndshell is set up (see above). This is where the name of your Ascore file is input.

Verify that you have created a subdirectory in your working directory called "midi". This is required for running Csndshell.

Run the Csndshell script. If you ran the install.sh script you can use the environment variable to start the script:

sh

$RUN_CSND

your_config_file

or, if you did not want to run install.sh, you can type in the full path to csndshell.sh:

sh

[full_path]/csndshell.sh

your_config_file

The csndshell.sh script will create some intermediate files in your working directory. This appears to be sloppy cleanup, but allows you to trace the output if you need to track a bug (or enlighten your misunderstanding). The MIDI file will be created in the subdirectory called "midi".

If you had the RMIDI option enabled in the config file (and you have SSH installed) the csndshell.sh script will attempt to copy the MIDI file to your remote PC (i.e., your sequencer) and prompt you for the login name and password. If you enabled the expect_rmidi option in the config file, the csndshell.sh script will attempt to silently copy the MIDI file to your remote PC (the login gets to be a burden).

Now you play the MIDI file with your midi player ("midi sequencer" in ALSA terminology). Assuming that you have connected your computer's MIDI output ports to your synthesizer(s), you should then hear sound from your synthesizer.

Common Problems

1. Hexxer

   Nearly everything in the Csndshell project is a scripting tool of some sort (shell script, AWK script, etc). The exception is a small program in the Mscore subdirectory called hexxer. A compiled file is supplied with the Csndshell package, but this file might not be compatible with your C libraries. If you get an error you should try compiling hexxer again. Instructions are given on the Mscore page:

   http://www.lumanmagnum.net/physics/mscore/index.html

2. Make sure that your working directory has a subdirectory named midi. The Csndshell script is self-contained in that it uses standardized, fixed directory paths for performing its tasks.