
[ reflector2midi ]
[ ============== ]

(c) under the GPL, A. Schiffler
aschiffler@home.com
schiffler@zkm.de

Please see file LICENSE.


[ Version History ]
[ --------------- ]

Ver 1.0 - Sat Apr 22 19:00:18 EDT 2000
- Initial release


[ Introduction ]
[ ------------ ]

reflector2midi is a utility program that can be used in conjunction with 
the asciireflector program to convert reflector text messages to MIDI 
signals. 

The function is simple: It will connect to a running asciireflector and
read all textlines passing through the reflector by fast polling. It does
not inject any text by itself. The text is parsed according to an pre-set 
configuration and MIDI control events are beeing generated if a match
is found.

The events are: Triggers ("T") (occurence of a word in a line), Counts ("C") 
(number of occurences of a character or a word in a line) and Values ("V")
(numerical value after a Pattern in a line).


[ Command Line Parameters ]
[ ----------------------- ]

Network settings:
 -host name      host to connect to (default: localhost)
 -port #         port to connect to (default: 1522)

Configuration settings:
 -config name    event configuration filename (default: events.cfg)
 -log name       configuration log filename (default: events.log)

Output settings:
 -mididev dev    midi device for output (default: /dev/midi00)
 -rate #         update rate for scanning reflector in Hz (default: 10)
 -channel #      midi channel to output on (default: 3)


[ Compilation ]
[ ----------- ]

To compile the source type
	make

Then run
	reflector2midi 
with the appropriate command line parameters. 

To test, connect the program to a running reflector and the MIDI
port to a program or device that can read or use the MIDI control message. 
Use telnet to inject appropriate messages into the reflector and check 
if the control codes arrive at the program processing the MIDI signals. 
See the default configuration file for a sample session.

Also a good idea during setyp is to add the -DDEBUG compile flag. Edit 
the Makefile to include this flag and then type
	make clean; make
to remake the program.

Now reflector2midi will output a log of debugging information, print the 
received text and the send MIDI controls.


[ The configuration ]
[ ----------------- ]

For your application, you have to create the appropriate event 
configuration.

Here is a copy of the file events.cfg included with the program that
explains the syntax of the configuration and the functionality of the 
event types in detail.

#
# Sample reflector2midi configuration file.
#
# Line Syntax:
#  - Lines preceeded by a "#" or empty lines are comments.
#  - All other lines are event entries with the following 4 components:
#     TYPE CONTROL SOURCE MATCH 
# where
#  - TYPE is a character defining the processing type which can be one of
#         T, C or V. 
#     "T" is a trigger event that happens when both SOURCE and
#         MATCH can be found in the line. Its MIDI output value is 1. 
#     "C" is a counter event. First the SOURCE gets matched and then
#         the number of occurences of MATCH is counted. This count 
#         corresponds to the MIDI output value.
#     "V" is a value event. After the SOURCH match the string MATCH is 
#         located. A numerical values after this string is used as value
#         for MIDI output. If the value is between 1-127 its passed 
#         unchanged. If the value is between 0.0 and 1.0 its scaled to
#         the range 0 to 127. Negative values are set to zero. Larger 
#         values to 127.
#   - CONTROL is a number that corresponds to the MIDI-Control used for this
#         event. It can range from 1 to 127.
#   - SOURCE is a string describing the source of the textline. Any text 
#         containing this string will get used for this event. 
#   - MATCH is a string used for pattern matching. Depending on the type
#         of event beeing processed it can be used in several ways. 
#
# All events the are added to the internal list, will be also written to a 
# log file to help debugging.
#
# Examples:
#
# The event-definitions below will generate the following midi events for
# each input line given:
#
# "Joe: Hello"               ---> Control 1 Value 1
# "Bill: Hello"              ---> Control 4 Value 1
# "Jack: Hello"              ---> nothing
# "Joe: AMADEUS ASKS AMY"    ---> Control 2 Value 4
# "Bill: Hello, AMY"         ---> Control 4 Value 1  + Control 5 Value 1 
# "Bill: X=0.5"              ---> Control 6 Value 64
# "Joe: X=45 Y=76"           ---> Control 3 Value 45 + Control 3 Value 76
# "Jack: Hello, AMY, X=88"   ---> nothing
#
T 1 Joe Hello
C 2 Joe A
V 3 Joe X=
V 3 Joe Y=
T 4 Bill Hello
C 5 Bill A
V 6 Bill X=
V 6 Bill Y=
