\documentstyle[11pt,twoside,refman,makeidx]{article} \def\version{C-1.1} \def\musictex{Music\TeX{}~} \def\miditex{MIDI2\TeX{}~} \pagestyle{myheadings} \markboth{\miditex \version}{\miditex \version} \def\whole{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{35}} \end{picture} } \def\half{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{34}} \put(0.5,0){\line(0,1){1}} \end{picture} } \def\quart{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{33}} \put(0.5,0){\line(0,1){1}} \end{picture} } \def\eighth{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{33}} \put(0.5,0){\line(0,1){1}} \put(0.5,0){\mus \symbol{40}} \end{picture} } \def\sixteenth{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{33}} \put(0.5,0){\line(0,1){1}} \put(0.5,0){\mus \symbol{41}} \end{picture} } \def\thirdysecondth{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{33}} \put(0.5,0){\line(0,1){1}} \put(0.5,0){\mus \symbol{42}} \end{picture} } \def\sixtyfourth{\setlength{\unitlength}{1em} \begin{picture}(1,1.5) \put(0,0){\mus \symbol{33}} \put(0.5,0){\line(0,1){1}} \put(0.5,0){\mus \symbol{43}} \end{picture} } \makeindex \begin{document} \bibliographystyle{plain} \newfont{\mus}{musicn20 scaled \magstep1} \begin{titlepage} \begin{maxipage} \vspace*{30mm} \begin{center} \Huge \bf \miditex\\ %[2\baselineskip] Version \version\\[2\baselineskip] \large a MIDI to \musictex translation program\\ %\vspace{5mm} \normalsize by\\[2\baselineskip] \Large H.J.P. Kuykens,\\ A.H. Verbruggen\\ %\vspace{5mm} \normalsize 20-7-'92\\ \vspace*{10mm} \begin{center} \framebox{\begin{minipage}{12cm}{\bf Note} This manual was originally written for the Pascal version 1.1 of MIDI2TeX. Therefore, information in this document may be irrelevant or exuberant for the C-source code version. \end{minipage}} \end{center} \vspace*{30mm} \input midi2tex.pic \vspace*{30mm} \end{center} \end{maxipage} \end{titlepage} \newpage \tableofcontents \newpage \section{Introduction} \label{introduction} \musictex{} is an extension of \TeX{} for typesetting polyphonic music written by Daniel Taupin. I was surprised by the excellent result of the output. However, the coding of a music piece with \musictex{} is quite laborious and difficult. The first thing which came to my mind was that certainly there must be people out there who developed software which could translate MIDI files into \musictex{} code. I placed requests on the international NEWS system. However, I did not get any response. That made me decide to develop such software myself. \miditex{} is the result. I hope that it can be useful for other people who, just like me, are involved in MIDI but do not have a good music type setting system and know how to get on with \TeX. If you are not familiar with \TeX{} at all I would recommend to find another software package to do musical typesetting. Setting up \TeX{} and \musictex{} on your machine and mastering it is an awesome job which gobbles up a lot of your time and disk space. But, once you master it.... \section{How to read this manual} \label{howtoread} If you are a regular user of \miditex then I suggest to switch immediately to section \ref{versions} to see what changes have been made since the last release and where to find more info about it. If you are familiar with \musictex but not with \miditex I suggest to read the complete manual. If you want a quick start than switch to section \ref{description} which describes all the command line options. In this manual two types of attention marks can be found in the left margin.\\ The one shown left \attention of this sentence asks your attention because there is some important information in that sentence.\\ The other one, \seealso{section \ref{howtoread}} shown left of this sentence, refers to another section in this manual which contains information related to the subject in that sentence. \section{What it does do} \label{whatdo} \miditex{} inputs a type 1 MIDI file %\footnote{See section \ref{bugs} for info about type 0 files} \seealso{section \ref{bugs}} and translates this into source code for \musictex. Several features of the program are listed below: \begin{itemize} \item Maximum of 16 tracks translated \item Vertical alignment of notes in staffs \item Generation of beams and slurs \item Text in MIDI file supported \item Changes in signature supported \item Quantizing \item Insertion of rests \item Skipping of tracks \item Combine several tracks into one instrument \item Selection of either violin, bass or alto clef for any track \item Reordering of tracks \item Changing vertical alignment \item Changing size of the music document \item Generate flats and sharps while taking into account the general signature \end{itemize} Most importantly, \miditex{} will do the massive job of coding note events in the MIDI file into \musictex{} notes. It speeds up the lay-out process of your sheet music tremendously. After the translation process you can manually adapt the \musictex{} source code to meet the desired lay out. \section{What it does not do} \label{whatnotdo} \miditex{} is not yet a very smart program. The vertical alignment of notes is not optimal. Complicated chord pieces are translated poorly. In general, additional editing of the \musictex{} code after the translation process is required to refine the output. \section{What is needed?} \label{needed} Software versions are available for PC compatibles (DOS), Macintosh and Atari ST. The versions are functionally identical. The Atari ST version includes a separate GEM based shell. The program itself needs approximately 90 kB and 10 kB for each track in the MIDI file to run properly. Of course you need \musictex. \musictex{} consists of several \TeX{} macro files and meta font files with music font definitions. The complete package is available on several bulletin boards and FTP sites. Recently I downloaded version 5.03 from rsovax.lps.u-psud.fr (in the directory {\tt /TeX/musictex}).\index{FTP sites} You need to acquire some knowledge about \musictex{} if you want to edit the source code after the translation process. Further you need \TeX. At the moment several good public domain packages are available. For the PC EM\TeX{} is a good one. On the Atari ST I use \TeX{} 3.1 by Christoph Strunk which I find pleasant to work with. OzTeX is available for the Mac. These packages are also available at FTP sites, PD services or bulletin boards. Last but not least use of this program is only of any use if you are working with MIDI files. A MIDI file contains musical information and is a standard file format which enables to exchange music pieces between different software packages. Although many MIDI sequencer software packages have their own file format, most of them also support standard MIDI files. \index{MIDI files} This manual assumes that you have some knowledge of \TeX{} and \musictex. If you are puzzled by any of the explanations in this manual see if reading the manuals of these packages can help you out. \section{Installation of the software} The PC version of the package comes in a ZIP file. Use any UNZIP program to decompress it to a target directory. \index{PC version!installation} The ST version comes in ARC'ed format ( V. 3.5). Copy the file MIDI2TEX.ARC to your (hard) disk and de-ARC it using any de-arc program. The example archive included in the distribution kit is ARC'ed and can be retrieved as described above.\index{ST version!installation} \section{The need of neat MIDI files} \label{neatfiles} MIDI files are usually created by recording keyboard (or other MIDI instrument) events in a sequencer. As a consequence, the timing of notes can be 'offbeat'. \miditex{} needs much more 'clean' files to enable correct translation. Therefore, it is necessary to first clean up the notes in a MIDI file to be processed. \index{MIDI files!need of neat} Many sequencers have a {\em quantize} function to align the start time of notes to a specific timing. \index{Quantization!MIDI files} That is a good start. If you have done that listen to the piece again to certify that all notes start at the correct position. The other thing you may want to do is to quantize the {\em length} of notes. Many notes which are played (usually short notes) do not fill the complete time they are supposed to be played. Usually the key is released earlier. If this is not corrected before starting \miditex{} the result is that after such notes a rest is placed. According to the program no note is sounding there! Some sequencers can quantize the length of notes too. If not, you can either edit them manually if your sequencer permits or you must do a lot of editing after processing of the file by \miditex. So, try to get your input MIDI files as neat as possible. \section{Description of command structure and options} \label{description} \index{Commands!described} A general call to \musictex{} looks like this: \begin{center} \tt midi2tex inputfile [outputfile] [-option1 [-option2 [...]]] \end{center} The options are: \begin{tabbing} {\tt -?xxxxxxxxxxx} \= \kill {\tt -?} \> A help screen\\ {\tt -s\#,\#,...} \> Skip tracks (default none)\\ {\tt -i\#,\#,...} \> Combine tracks into one instrument (default none)\\ {\tt -b\#,\#,...} \> Code staffs with bass clef (default violin)\\ {\tt -a1\#,\#,...}\> Code staffs with alto 1 clef \\ {\tt -a2\#,\#,...}\> Code staffs with alto 2 clef \\ {\tt -a3\#,\#,...}\> Code staffs with alto 3 clef \\ {\tt -a4\#,\#,...}\> Code staffs with alto 4 clef \\ {\tt -o\#,\#,...} \> Order the tracks (default original order)\\ {\tt -q\#} \> Quantize (default off)\\ {\tt -p\#,\#,...} \> Vertical part times (default type 4, quarter note)\\ {\tt -f\#,\#,...} \> Force beams to zero slope\\ {\tt -h\#} \> Set horizontal size of music document\\ {\tt -v\#} \> Set vertical size of music document\\ {\tt -m\#} \> Set musicsize\\ {\tt -e\#} \> Set Elemskip size\\ {\tt -k\#} \> Set key sign\\ {\tt -x} \> Enable batch processing (ST version only)\\ {\tt -dTYPE} \> Generate debug information (default none) \end{tabbing} The input file name is any valid DOS name. If the extension is omitted the default {\tt .MID} is assumed. The output file name is optional. If omitted the input file name is used with extension {\tt .TEX}. The options are described in more detail below. \begin{description} \item[\bf -?, help screen] The program displays information on how to enter a correct command line and a listing of available options. \index{Commands!-?} \item[\bf -s, skip tracks] Occasionally you might want to skip a track because you don't want any output from it to appear on your scores. You can suppress output from a track by including the {\bf -s} option in your command line. The numbers of the tracks(s) you want to skip immediately follow the option. For instance if you want to skip a drumtrack on track 4 your command line should include: {\tt -s4}. \index{Commands!-s}\index{Skip tracks} The meta events in a skipped track {\em ARE} processed as they may contain information about timing or key signature. The first track in a type 1 midi file is usually only used to store information about timing, key signature, etc. Therefore {\em this track is skipped by default}. If for any reason you want to prevent skipping of this track then include {\tt -s1} in the command line. \item[\bf -i, instruments] In \musictex{} it is possible to assign two or more staffs to one instrument. For example they can be the left and right hand of a piano piece. This option can be used to assign two or more tracks to one instrument. The tracks are entered as numbers directly after {\tt -i}, separated by comma's. For instance if a piece contains 6 tracks and you want to assign track 2 and 4 to one instrument your command line must contain the option: {\tt -i2,4}. \index{Commands!-i}\index{Instrument staffs} \item[\bf -b, bass clef] \musictex{} enables coding of music using different clefs. Most used are the violin and bass clef. \miditex{} enables the assignment of the bass clef to one or more tracks. If omitted, the default violin clef is used. For instance, to assign the bass clef to track 2 of a MIDI file include {\tt -b2} in the command line. \index{Commands!-b}\index{Bass clef} \item[\bf -a1..a4, alto clefs] Assign an alto clef to any of the tracks. For instance, to assign the alto 1 clef to track 3 of a MIDI file include {\tt -a13} in the command line.\index{Commands!-a1..4}\index{Alto clefs} \item[\bf -o, order track] The ordering of tracks in your MIDI file may not comply with the order you want the tracks to appear on the output. With this option you can redefine this order. Here is an example: consider a MIDI file containing 3 tracks. Normally the order of the tracks on your output will be 1, 2, 3. If you want to alter this order into 2, 3, 1 you must include the option {\tt -o2,3,1} in the command line. It is important that you include \underline{ALL TRACKS} \attention in this option. If there are 5 tracks in the MIDI file there must be 5 numbers in the option string. Don't forget to include the first track in the string. By default it is skipped in the output but you {\em must} include it in this command. If you forget one \miditex{} will exit with an error. So, before using this command you must be sure how many tracks are included in the MIDI file. The best way to use this option is to first translate the MIDI file without this option. Examine the output and determine the order of the tracks that you want. Than retranslate the MIDI file with the {\tt -o} option included. \index{Commands!-o}\index{Ordering tracks} \item[\bf -q, quantize] Quantizing involves the rounding of start times of notes. As stated in section \ref{neatfiles} quantizing is a good tool for cleaning up the notes in your MIDI file. If you do not have this opportunity on your sequencer and your output comes out ugly with lots of rests inserted everywhere, try to use this option. The quantize option does two things: \begin{itemize} \item quantize the start time of notes \item quantize the length of notes \end{itemize} The number after the {\tt -q} option determines the quantization time. Use table \ref{quanttimes} to determine the quantization time: \index{Commands!-q}\index{Quantization!by \miditex} \begin{table}[hbtp] \label{quanttimes} \begin{center} \begin{tabular}{|c|c|} \hline quant. note & number \\ \hline \whole & 1 \\ \hline \half & 2 \\ \hline \quart & 4 \\ \hline \eighth & 8 \\ \hline \sixteenth & 16\\ \hline \thirdysecondth & 32\\ \hline \sixtyfourth & 64 \\ \hline \end{tabular} \caption{The quantization numbers} \end{center} \end{table} \item[\bf -p, part time] \musictex{} is designed to code notes in a vertical way. The notes at different tracks that start at the same time should be aligned to each other. Therefore in \musictex{} you can split up a measure into separate parts. The starts of such parts are aligned above each other. \index{Commands!-p}\index{Defining!parts} \miditex{} follows this philosophy. By default it separates the measure into parts with a length of the denominator of the signature. If you want to change this part time use this option. Use table \ref{quanttimes} to determine what number you should enter after the option. For instance if you want the separation time to be the length of an eighth note instead of a quarter note include {\tt -p8} in your command line. \item[\bf -f, force zero slope] This option forces the slopes of the generated beams to be zero. The beams will be oriented horizontally. \index{Commands!-f}\index{Defining!zero slope beam} \item[\bf -h, horizontal size] With this option a horizontal size can be set other than the default defined in \musictex{} (160 mm). \attention The parameter should be in 0.1mm. This option will output the proper sizing command in the source code. More important is that this command is used to append line and page breaking commands at the proper positions in the source file. \index{Commands!-h}\index{Defining!horizontal size} \item[\bf -v, vertical size] With this option a vertical size can be set other than the default defined in \musictex{} (240 mm). See {\tt -h} option for further details. \index{Commands!-v}\index{Defining!vertical size} \item[\bf -m, musicsize] With this option a choice can be made between 20pt and 16pt. The parameter must be either 16 or 20.\\[0.3\baselineskip] As an example we might want to produce a music document with width 100 mm, height 200mm and 16 pt musicsize. The option string should than include: {\tt -h1000 -v2000 -m16}. \index{Commands!-m}\index{Defining!music size} \item[\bf -e. elemskip] Notes in \musictex are spaced by the (\musictex) variable \verb@\elemskip@. Default values are set during initialization of \musictex. In previous versions of \miditex \verb@\autolines@ was used to alter the spacing of notes. Instead of using this macro in this version \verb@\elemskip@ is now altered directly. This only happens when the size of the document is changed in any way (-m,-v,-h,-e). If you're not satisfied with the spacing of the notes you may use this option to directly alter the value of \verb@\elemskip@. The value should be in pt. Changing the value of \verb@\elemskip@ in this way does not corrupt line and page breaking. An example: When using musicsize 20 the elemskip is 10 by default. If you want to reduce the space between the notes you must include the option {\tt -e8} in your command string. \index{Commands!-e}\index{Defining!elemskip size} \item[\bf -k, key sign] This option sets the keysign of the total music piece. Presently \miditex does not allow to set a key sign for individual tracks. The parameter following the option denotes the number of flats (negative sign) or sharps (positive sign). For instance to code a piece with four flats the command line should include: {\tt -k-4} \index{Commands!-k}\index{Signature!command} \item[\bf -x, batch proc.] This option is only available on the ST version. It skips the message: {\tt hit key to exit} which appears after processing of a file. Including this option on the command line in a batch file which contains calls to \miditex enables continuous execution. \index{Commands!-x}\index{Batch processing} \item[\bf -d, debug info] This option generates debug information. There are three ways to output this info: screen, file or printer.This is the way to select the debug type: \index{Commands!-d}\index{Debugging!options} \begin{tabbing} {\tt to printer}xxx \= -dPRINTER\kill {\tt to screen} \> -dSCREEN\\ {\tt to file} \> -dFILE\\ {\tt to printer} \> -dPRINTER \end{tabbing} File output is written to a file with the name of the input file and extension {\tt .MLG}. I do not believe that this option is of any use to anyone who is not familiar with the internal structure of the program. However, if for any reason the program should crash at least you know at what point this happened. In section \ref{bugs} \seealso{section \ref{bugs}} further suggestions for its use are given.\\ {\bf Warning:} \attention this option creates a {\em huge} amount of ASCII data. A single page of typeset music will generate about 65kB of debugging info depending on the number of notes in each measure. \end{description} \section{During processing} During run time the program displays the measure it currently processes on the screen between square brackets. This is the sign that the program is actually doing something useful. In some cases you may want to decide to abort the processing. In the PC version you can do so by pressing the 'q' on the keyboard. On the Mac the translation process can be interrupted by typing command-period. The \musictex{} file and the log file are closed and the program exits. See section \ref{bugs} for additional info. The code generated until the {\bf q} key was hit can be translated normally. Code is appended which correctly closes the music document. After completion of the translation process the program displays the number of pages it has coded. \section{Key signature and transposition} Accidental note processing can be performed either by \musictex{} or by \miditex. You may choose the method you prefer. \subsection{Key signature by \musictex{}} \index{Signature!by \musictex{}} From version 4.5 (and maybe earlier versions too) it is possible to let \musictex{} figure out when flats or sharps should be inserted. To do this, translate the MIDI file {\em without} specifying any key signature. After the translation proces edit the resulting \musictex{} file. In the preamble you will find the command \verb+%\relativeaccidentals+. Uncomment it by removing the \% sign. Now edit the {\verb+\generalsignature+} command to the required number of flats (negative sign) or sharps (positive sign). During processing \musictex{} will now figure out where to put flat and sharp signs. \subsection{Key signature by \miditex{}} \index{Key signature!by \miditex{}} \miditex{} contains a facility to generate sharps and flats taken into account the general key sign. To use this method translate the MIDI file with the option {\tt -k}. The parameter of the -k option should be the number of flats or sharps of the key sign. Now after the translation process the file is ready for processing by \musictex. \subsection{Transposition} \index{Transposition} Currently \miditex{} does not have the ability to transpose parts because \musictex itself is quite capable of doing that. Including the \musictex \verb@\transpose=@ command in the preamble allows up or down tranposition of tracks. See section 2.11 of the \musictex manual \cite{Taupin} \seealso{reference \cite{Taupin}} for further details. \section{Line and page breaking} \index{ Line and page breaking} \miditex keeps track of the space that is occupied by the typesetted music and inserts \verb@\alaligne@ and \verb@\alapage@ at the proper moments. It uses an \verb@\elemskip@ of 10pt for musicsize=20 and 8pt for musicsize=16. Inclusion of \verb@\autolines@ is not required anymore. \verb@\elemskip@ can be directly altered with the {\tt -e} option. When translating a file into a document with musicsize 16 you may end up in a {\tt \TeX~~capacity exceeded~} error. During processing all measures are stored in memory until an \verb@\alapage@ is encountered. When selecting musicsize 16 there are so many notes on a single page that occasionally \TeX~~may run out of storage space. There are two ways out: use B\TeX~~ or translate the MIDI file with musicsize 20. \section{The shell program (ST version only)} The main program \miditex{} can be controlled by the previously described options. The current operating system of the Atari-ST can only handle a command string of limited length. I wrote a small GEM based shell which avoids this problem. The shell can be started by double clicking on the program name ({\tt M2TSHELL.PRG}). A screen-wide form appears. This form contains edit fields for the different options. To edit a box first click on it with the mouse. The cursor appears in the box and you can use the keyboard to edit the string. You should {\em not} \attention include the option identifier in the string. Only the parameters should be entered. For instance, if you want to skip tracks 2 and 3 just put {\em 2,3} in the box and {\bf not} {\em -s2,3}. One exception is the '{\em other} box'. Here you can enter other valid \miditex options. As this box is not tied to a specific option the option identifiers {\em must} be included if this box is used. Currently there are no boxes to allow selection of the alto clefs. The only way to select them using the shell is by inserting proper option strings in the '{\em other} box'. A file can either be selected by editing the file selection box or by using the file selector by clicking on the button above the file selection box. \section{An example of using \miditex{}} Included in the package is an example MIDI file. This file will be used to demonstrate how to use \miditex. The example file was generated by Cubase. Track 1 contains Cubase mastertrack information (time signature, clef etc.) and no notes. \miditex skip this track by default. Translation of the file is now initiated by entering \begin{verbatim} MIDI2TEX EXAMPLE -dFILE \end{verbatim} The screen will show some program info and start executing. After termination of the program two files are generated. One is called EXAMPLE.TEX and the other EXAMPLE.MLG. Use any editor to inspect the content of the files. EXAMPLE.TEX will look like: {\small \begin{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % MIDI2TeX C-version V 1.1 translation % of MIDI file : % example.MID % % Written by Hans Kuykens, Ad Verbruggen %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \input musicnft \input musictex \input musicadd \input musictrp \normal \def\nbinstruments{3} \generalsignature{0}\relax \def\thename{example} % \centerline{\enorme PUT A NAME HERE and remove } \medskip\centerline{\moyen \thename} \rightline{translation by MIDI2TeX} \rightline{by H.J.P. Kuykens} \def\date{\number\day -\number\month -\number\year} \headline={\ifnum\pageno>1 \otherpage \else\frontpage\fi} \def\frontpage{\hfil \tenrm\date} \def\otherpage{\tenrm \thename \hfil \tenrm\date} \generalmeter{\meterfrac{4}{4}}% %\raggedlinestrue % uncomment for ragged right lines %\relativeaccidentals \debutmorceau %measure 1 \NOtes\uptext{Track 3} \hl q&\uptext{Track 2} \soupir &\uptext{Track 1} \qu J\enotes\relax \temps\NOtes&\zq j\zq {^k}\qu g&\soupir \enotes\relax \NOtes\ibl0o{0}\qb0p\qb0q&\soupir &\qu G\enotes\relax \NOtes\qb0p\tbl0\qb0o&\zq k\zq j\ql g&\soupir \enotes\relax %measure 2 \barre \NOtes\cl n\ds &\soupir &\qu J\enotes\relax \NOtes\hlp l&\zq {^k}\zq j\ibl1g{-1}\qb1g\zq j \zq k\tbl1\qb1g&\qu G\enotes\relax \temps\NOtes&\soupir &\qu {_I}\enotes\relax \temps\NOtes&\zq g\zq {_i}\qu {=k}&\qu {=I}\enotes\relax %measure 3 \alaligne \NOtes\ibl0k{0}\qb0k\qb0l&\soupir &\qu J\enotes\relax \NOtes\qb0n\qb0k&\zq j\zq {^k}\ql g&\soupir \enotes\relax \NOtes\qb0l\qb0o&\soupir &\qu G\enotes\relax \NOtes\qb0n\tbl0\qb0l&\zq k\zq j\qu g&\soupir \enotes\relax %measure 4 \barre \NOtes\ccl k\pt g\ds &\soupir &\qu J\enotes\relax \temps\NOtes\hl j&\zq j\zq {^k}\ql g&\qu I\enotes\relax \temps\NOtes&\zh {_i}\zh g\hu {=k}&\qu J\enotes\relax \finmorceau \bye \end{verbatim} } Now you can process EXAMPLE.TEX directly with \TeX. Be sure not to use \LaTeX{} because \TeX{} cannot hold that many macro definitions. After processing the above example you will find out that the score comes out pretty ugly. The bass notes on the first score line are way beyond and the melody line is on score 3. Now rerun MIDI2TeX with the following command: \begin{verbatim} MIDI2TEX EXAMPLE -o1,4,3,2 -b2 \end{verbatim} This command now reorders the tracks and assigns the bass clef to the second track. The resulting score will now look much better.\\ In addition to the example file mentioned above I also included some MIDI files which I received from Volkmar Zitz which were a great help for tracking down the errors in previous versions. Theses files are ARC'ed into EXAMPLES.ARC. There is also a batch file included which starts the translation processing of these files. This is of course only for DOS users. ST users will have to do it manually unless they are using a shell. \section{Notes to versions} \label{versions} \begin{description} \item[test version 1] This is the first external release of the software. It is distributed for evaluation purpose to persons who previously have shown interest in the program. \item[test version 2] This is the second test release of the software. Shortly after the release of the first test release I discovered some disturbing bugs. I wanted to get rid off these before sending it to other people who have shown their interest after a message on NEWS. New features in the second test version are: \begin{itemize} \item Processing can now be stopped by pressing the 'q' on the keyboard. \item The program now recognizes slur notes and generates source code for it. \item Bug during insertion of rests removed \end{itemize} \item[test version 3] A lot of bugs were found in the previous version and solved. Most important ones are listed below: \begin{itemize} \item Reading of Key sign corrected (this caused crashes) \item Running status events in the MIDI file now supported (also crashed the program) \item MIDI files outside current directory in M2TSHELL.PRG now selectable \item Problems in {\em 'Chordfinder'} solved (caused run time errors) \item The slope of the beam is now calculated from the number of notes in the beam and the minimum and maximum note value within that beam \item Chaining of beams to higher/lower order corrected. Also, single flag beam notes are now supported. \item Clearing of beam and chord arrays forgotten which resulted in recognition of notes from previous measures. \item The timing of the measure parts is now determined by the numerator of the signature. \item Occurrence of accidental notes now only produce one flat/sharp sign. \end{itemize} {\bf New features} in the third test version are: \begin{itemize} \item Line and page breaking of the scores by insertion of \verb+\alaligne+ and \verb+\alapage+ commands. This is done by keeping track of the number of notes written. \item Occurrence of meta events in track 1 are now handled properly at the right measure \item Size of score and document may now be adjusted \item \verb+\temps+ inserted before measure parts with no beams open \item \verb+-h+ option from previous versions changed into -? \item \verb+-k+ option added to set general key signature \end{itemize} \item[version 1.0] \begin{itemize} \item Correction in the generation of \verb@\alaligne@ and \verb@\alapage@ commands. Removed \verb@\autolines@. \item Track 1 skipped by default. \item Batch processing option included (ST only). \item Slur bows better due to enhanced filling of line. \item Changed log file name extension from .LOG to .MLG to prevent overwriting by \TeX. \item Added option -a1..-a5 to allow the use of alto clefs \item Added option -e to allow changing the elemskip value \end{itemize} \item[version 1.1] \begin{itemize} \item A small bug during unskipping track 1 removed \end{itemize} \item[version C-1.1] \begin{itemize} \item The complete Pascal code was translated into C using P2C. Additional coding was necessary to get the code running. The current source compiled and linked succesfully using Turbo-C on a PC (small memory model), THINK-C on the Mac, UNIX and VAX machines using standard C-compilers. See section \ref{technotes} for further information on compiling the source code. \end{itemize} \item[future plans] \begin{itemize} \item Shifting of notes occuring in a chord \item Selection of only part of the MIDI file to be translated. \item Automatic transposition of measures that contain notes exceeding the \musictex note value limits. \item Further development of the portable C-version of the program for other platforms. \end{itemize} \end{description} \section{Bugs \& problems} \label{bugs} I encourage everybody to report bugs or problems that you encounter back to me so that these can be omitted in a next release. Also, I am open for suggestions for enhancement of both the program and the manual. Piet van Oostrum suggested that this same program should also be able to translate type 0 MIDI files. I have adjusted the source code such that type 0 files now do not induce an error exit. I tested a few of such files without succes. Nevertheless, I decided to allow processing of such files for those of you who wish to experiment. When a type 0 file is encountered a warning is displayed on the screen that the result may be unpredictable. I would be pleased if anybody would share his experience with translating type 0 MIDI files with me. Bugs may appear in two different forms: run-time errors and infinite loops. The first one generates an error-exit: the open files are closed and the program terminates. The second type of bug can be recognized by the fact that the displaying of processed measures stops. Just hit the 'q' and the program terminates. Error messages and warnings are listed in the appendix. If you find any problems I suggest to run the program in debug mode, %\footnote{see warning in description of debug option} \seealso{section \ref{description}, -d option} preferably in FILE mode. Then, send the MIDI file and a small note explaining the problem to me. I'll try to collect the problems and avoid them in a next version. Please send compressed (ARJ, ARC, ZOO, LZH, ZIP) files to:\\ \begin{center} Hans Kuykens\\ Spaarndammerplts. 7b\\ 1013 XP Amsterdam\\ The Netherlands\\ e-mail : kuykens@amc.uva.nl ( until 1-10-94) \end{center} Problems with the C-code may also be addressed to :\\ \begin{center} Ad Verbruggen\\ e-mail : ahv@dimes.tudelft.nl \end{center} ~\\ The following problems are known to me: \begin{enumerate} \item Notes which have a MIDI value larger or smaller than the notes accepted by \musictex{} are coded as question marks (?). This causes \TeX{} to stop processing. One way to solve this problem is to octivate the measure. Automatic octivation is {\em not} (yet) implemented in \musictex. \item Flat and sharp signs may disappear under a preceding note in score lines with very close spacing. This is a \musictex problem. \item Notes in a chord are not shifted in any way. \item Closing of double sounding notes may corrupt the beaming business. \item The program fails to run on the Atari TT. \end{enumerate} \section{Technical notes for developers} \label{technotes} MIDI2TeX was originally written in Turbo Pascal. As a consequence, portabilty was poor. I received many requests for the source. A few people have tried to generate a more portable version but to my knowledge nobody ever came up with a working version. I decided to do the job myself (Aug-1993). Somebody on the net was kind enough to pass the Pascal source code (V 1.1) through a very good Pascal-2-C converter. That produced 95 \% of the C-code. It still needed editing to cope with pointers and the buffered IO. One particular problem that occurred is that on the Atari ST the bytes in an integer/longint are stacked in reverse order compared to the PC and Mac. To solve this problem the routines ReadLongInt and ReadInteger (in \verb@TP_M2TF4.C@) were rewritten. The proper ones may be selected by inserting \#ifdef statements. In a joint effort with Ad Verbruggen we were able to generate a working portable version. Exectuables have been generated on \begin{itemize} \item PC compatible (MSDOS), using Turbo-C \item Macintosh, using THINK-C \item Unix machines, C-compiler unknown \item VAX-VMS machine, C-compiler unknown \end{itemize} This source code is now available on the network for those who are interested to port the C-code to other platforms. I invite C-experts who are interested in implementing the program on another platform to get a copy of the code and generate the executable. In return I would like to ask to make this executable available to other network users. Please inform me about succesfull compilation and send me back the edited source- and make files. I'll try to glue them together to get source which is portable to many systems. \subsection{Systems, instructions and comments} \begin{description} \item[DOS] I used a small library model to link the modules. When I tried to use other than that, the program would crash at the first file read instruction. As my knowledge about C is poor I was unable to track down the reason for this. As a consequence of the small memory model the read buffers could only be 1024 bytes long. \item[VAX] Compile all source files using \verb@cc tp_m2t16.c,tp_decl.c,...@.\\ Before linking : \verb@$define lnk$library sys$library:vaxcrtl.olb@.\\ Then : \verb@ $link tp_m2t16,tp_decl,tp_misc,tp_midi,...@.\\ This gives you the executable with extension \verb@.EXE@. Now, to enable command line arguments define a foreign command by :\\ \verb@MIDI2TeX == "$ $disk:[....]tp_m2t16.exe@. The string \verb@$disk:[...]@ can be inspected on the local system by typing : \verb@show default@. Now the program can be run by typing : \verb@MIDI2TEX midifile@. \item[Macintosh] MacTraps should be included in the link process. Enable {\em Require prototypes} in Edit Menu : Options : Language Settings and check {\em Far Data} in Project Menu : Set Project Type. Code should be segmented. \end{description} \section{License} \begin{center} \large Copyright (c) 1992 by H.J.P. Kuykens. All Rights Reserved. \end{center} You are free to use, copy and distribute \miditex{} and inspect or edit the source files for non-commercial purpose provided that : \begin{itemize} \item the name(s) of the author(s) is/are not removed from the manual nor from the program itself \end{itemize} For commercial purpose \miditex is shareware. That is, if \miditex is used to generate sheet music with the intention to distribute it for commercial purpose a fee of \$~25,- is required. The software comes without any warranty. The responsibility for it's use is completely for the user. The authors are not responsible for any damage arising from use of this program whether caused by negligence or other fault on the part of the authors or by any other cause. \section{Acknowledgement} Although I wrote the code myself several people have made valuable suggestions to me. In particular I would like to mention Angelo Melis with whom I exchanged a lot of ideas and Ad Verbruggen whose enthusiasm made it possible to develop the C-version of the program. Also, Noel (?) attributed to the ideas for this program. After sending off test versions I received bug reports from: Volkmar Zitz, David Channing, Vincenzo de Florio, John Richards, Piet van Oostrum, Mark Torrance, Michal Tomczak-Jaegermann. I would like to thank them for their valuable help and suggestions. These bug reports are a tremendous help in finding and solving bugs in the software. Also Daniel Taupin and Dale (Gold?) helped me out when I needed some specific 'inside \musictex' information. Steve Chamberlain has passed the Pascal code through P2C (Caltec) to obtain the C-code. \nocite{defuria,Taupin,turbo-c} \bibliography{midi2tex} \newpage \appendix \label{appendix} \section{Error and warning messages} \begin{enumerate} \item No input file specified, or file does not exist \item MidiFile track {\#} is not ok \item Found a NoteOff without a NoteOn \item Can only translate MIDI files of type 1, sorry$\ldots$ \item Nil pointer detected in NoteOff search \item No\null. of order indices does not correspond with No\null. of tracks in file \item Staffindex out of range, you tried to change a staff attribute which I cannot handle \item Heap exhausted during initializing memory \item The noteheap appeared to be empty during a note request to the noteheap \item A note value exceeded 127, probably a program bug \item Invalid PartTime entered, only one of 1, 2, 4, 8, 16, 32 allowed \item Invalid quantization time entered, use switch -? to get proper range \item Can only define one multi-staff instrument in this version \item Definition of an instrument of one track is useless \item The Slur-array is exhausted, too many slurs (9) for MusicTeX \item Process terminated by user \item The Beam-array is exhausted, too many beams (9) for MusicTeX \item -h and -v option can only take one parameter \item -m option parameter must be either 20 or 16 \item Unknown error, probably a bug$\ldots$ \end{enumerate} \section{Package contents list} The following files are included in the \miditex{} software package:\\ {\Large PC version\\} \begin{tabbing} {\tt MIDI2TEX.EXE:}xxxxxx \= the executable\kill {\tt MIDI2TEX.EXE:} \> the executable\\ {\tt EXAMPLE.MID:} \> an example MIDI file\\ {\tt EXAMPLES.EXE:} \> additional example MIDI files\\ {\tt MANUAL.TEX:} \> the \TeX{} manual you are reading right now\\ {\tt MIDI2TEX.BBL:} \> the bibliography file\\ {\tt MIDI2TEX.PIC:} \> the frontpage logo\\ \end{tabbing} ~\\ {\Large ST version\\} \begin{tabbing} {\tt MIDI2TEX.EXE:}xxxxxx \= the executable\kill {\tt MIDI2TEX.TTP:} \> the executable\\ {\tt M2TSHELL.PRG:} \> the GEM shell to call {\tt MIDI2TEX.TTP}\\ {\tt EXAMPLES.ARC:} \> additional example MIDI files\\ {\tt M2TSHELL.RSC:} \> the resource file for the shell\\ {\tt EXAMPLE.MID:} \> an example MIDI file\\ {\tt MANUAL.TEX:} \> the \TeX{} manual you are reading right now\\ {\tt MIDI2TEX.BBL:} \> the bibliography file\\ {\tt MIDI2TEX.PIC:} \> the frontpage logo \end{tabbing} {\Large Source\\} \begin{tabbing} {\tt MIDI2TEX.EXE:}xxxxxx \= the executable\kill {\verb@TP_DECL.C@ :} \> source file, declarations\\ {\verb@TP_MISC.C@ :} \> source file, miscelaneous functions\\ {\verb@TP_DEBUG.C@ :} \> source file, debug functions\\ {\verb@TP_MIDI.C@ :} \> source file, MIDI parser\\ {\verb@TP_M2TF4.C@ :} \> source file, buffered file IO \\ {\verb@TP_HEAP1.C@ :} \> source file, defines and handles a heap of notes\\ {\verb@TP_M2T16.C@ :} \> source file, the main program \\ {\verb@ *.H@ :} \> the header files\\ {\tt EXAMPLE.MID:} \> an example MIDI file\\ {\tt MANUALC.TEX:} \> the \TeX{} manual you are reading right now\\ {\tt MIDI2TEX.BBL:} \> the bibliography file\\ {\tt MIDI2TEX.PIC:} \> the frontpage logo \end{tabbing} \clearpage \printindex \end{document}