Community Theatre is a type of live theatre in which
many people want to act, sing and dance on stage, but,
compared to professional theatre, there is little
support for them.  In particular, performance are
often done in theaters without fly space or wings,
and generally there is little equipment.

To address one aspect of the lack of adequate
equipment, this program schedules the sharing of
microphones between actors, minimizing the number
of microphones required and maximizing the amount
of time available to remove a microphone from one
actor and place it on another.  Because backstage
personnel are also in short supply in Community
Theatre, the actors can be tasked with doing these
microphone transfers themselves.

The input for the allocate_microphones program is
a text file which describes the activities in
the play to be performed.  The following information
appears in the text file: the names of the characters,
the names of the actors, which characters are played
by each actor, and the timeline of the play, showing
when each character enters, speaks and exits.

When developing the description, keep in mind that
in Community Theatre not all characters will be cast 
until late in the rehearsal process.  Characters
without actors assigned are given to unique, created
actors until their assignments are established.
This is the worst case for microphone assignments,
so it can let you determine early if you need to
borrow more microphones from another production
company, or if you need to beg the director to
assign a part to an actor who already has a
microphone.

The output of the program is several lists, most 
importantly instructions for each actor showing 
when and from whom he gets his microphone, and when 
and to whom he gives it.

The input file for the allocate_microphones program
has a simple syntax.  Comments start with // and
extend to the end of the line.  Blank lines, and lines
containing only a comment, are ignored.  Lines which
are not ignored have two forms: commands and clauses
that modify the commands.

Command lines start with a left square bracket and
the command is completed by a right square bracket.
The first word after the left square bracket is the
name of the command, and the text after the name
and before the right square bracket is its argument.
For example:

[show The Perils of Pauline]

is the "show" command with argument "The Perils of
Pauline".  Clauses are lines of the form
keyword=value.  The effect of a clause is to add
information to the last command.  For example:

[actor Pearl White]
microphone=1

specifies that there is an actor named Pearl White,
and we prefer that she be assigned microphone number
1.

In describing the timeline for the play, we omit the
actual lyrics, music and dialogue, but we describe all
of the other events.  There are defaults to simplify
data entry, but in general everything must be specified.
Here is an example:

[page 1]
[act 1]
[scene 1]
[enter Pauline]
[song Where is my Hero?]

This example states that act 1 scene 1 begins on page 1,
that a character named Pauline enters, and that a song
named "Where is my Hero?" is sung.  The program will
deduce from this information that the actor playing
Pauline will need a microphone.

Later in this document I will provide a complete
description of the commands and their clauses.  Here, I will
present a short example of a show, with plenty of
annotation.

[show The Perils of Pauline]  // name the show

[character Pauline]  // list the characters
[character Harry Marvin]

[actor Pearl White] // list the actors by importance
[actor Crane Wilbur]

// each role associates an actor with one or more characters
[role]
actor=Pearl White
character=Pauline

[role]
actor=Crane Wilbur
character=Harry Marvin

[page 1]
[act 1]
[scene 1]
[enter Pauline]  // Pauline appears on stage
[song Where is My Hero?] // she sings a song
[page 2]
[enter Harry Marvin]  // the hero enters
[song I Have Come to Save You] // he also sings a song
[page 3]
[exit Harry Marvin]  // the hero leaves 
[enter Raymond Owen]  // and the villian arrives
// note that the character of Raymond Owen does not yet
// have an actor assigned.  When the assignment is made
// we will add another [role] above.
[begin sound Train Approaching]  // the audience hears the train
[page 4]
[enter Harry Marvin] // the hero returns to save Pauline
[page 5]
[end sound Train Approaching] // the train sound vanishes
[exit Raymond Owen] // the villian departs
[page 6]
[exit Pauline]  // the other characters exit
[exit Harry Marvin]
[end show] // the show ends after just 6 pages

"The Perils of Pauline" requires three microphones, because all three
actors appear on stage at the same time.  This example is good for
illustrating the syntax of the play description file, but a longer
example is needed to show the value of using a program to
allocate microphones.  See "The Music Man" in the examples directory,
which uses 24 microphones to cover 46 actors.

The output of the allocate_microphones program is several tables,
formatted as fragments of a LaTeX document.  Each table is in a
separate output file.  The output file names are composed of
the output root name followed by the name of the table.
The tables are as follows:

.activities.tex
	For each page in the show, lists who is on stage, what
song is sung, and what sounds are being played for the audience.
Also lists the act, scene, start time and duration of the page.
This information is used to debug the input file.

.actors.tex
	For each actor, describes when and from whom he gets his
microphone, and when and to whom he gives it up.

.assignments.tex
	For each microphone, describes who uses it and when.  The
microphone operator can use this list to relate microphones to actors.

.microphone_channels.tex
	Names the most important character who uses each microphone.
This information is formatted to fit on the mixing board below each
microphone slider.

.microphone_labels.tex
	For each microphone, names the actors who will use it.  Place
these labels either on the microphone, or, better, at the location where
the microphone is stored between shows.  I have found that a shoe tree
can hold up to 24 microphones conveniently.

.microphone_moves.tex
	Lists in page number order each microphone move between two
actors.

.microphone_switching.tex
	Lists in page number order when each microphone should be switched
on and off.  The microphone operator pastes these notes into his script
so he can control the "mute" button for each microphone, and move microphones
between groups.

.microphone_switching_annotated.tex
	Contains the same information as .microphone_switching.tex but
in an expanded form, with character names.  If you have a mixer
board with a sequencer, this list is intended for the person
who programs the sequencer.

.DCA_usage
	Summarizes the microphone switching information, showing which
microphone is in which DCA on each page.  If you have a sequencer which
can rename DCAs on each cue, you can use this display to debug your
sequencer programming.  In addition, if characters have been allocated
poorly to DCAs, this overview can guide you into gathering characters
into groups, or splitting groups between acts.

.parameters.tex
	Contains the show name and whatever was specified after
	[show], particularly the Venue and Designer.  This information
	can be used in the microphones template file.
	
.stage_manager_after_show.tex
.stage_manager_at_intermission.tex
.stage_manager_before_show.tex
	These three lists show the stage manager who has each microphone
at the specified times.

.stage_manager_during_show.tex
	If the stage manager, rather than the actors, oversees microphone
swapping, this list shows him what he must do, and when.

In addition to the LaTeX output, there are the following outputs:

.csv
	A spreadsheet, in comma-separated-value format, showing 
when each microphone is in use, and by whom.

.X32TC.txt
	A database, in sqlite3 dump format, for the program X32 Theatre Control.
It switches on actor's microphones as needed, and places
groups in DCAs so they can be controlled together.  X32 Theatre Control
is a program to extend the capabilities of the Behringer X32 audio mixer.
Convert this file to an sqlite3 database for X32 Theatre Control with
	rm -f file.X32TC.sqlite3
	sqlite3 file.X32TC.sqlite3 -init file.txt.X32TC.txt ""

To place these lists in a document requires LaTeX, a document preparation system
used for scientific articles.  Each of the above .tex files is included in
a master document using TeX's \include feature.  The examples contain
files of the form <show_name>_microphones.tex
that you can use as templates.  Edit them as you see fit
(for example, change my name to yours) and create PDF files by
running pdflatex twice: the first run computes the page numbers
and the second places the table of contents on the first page.

Because you don't generally need to see the timeline in
the later stages of production, and it can be quite long,
I use a separate template for it, named <show_name>_timeline.tex.

Questions and Answers

Before I present the complete syntax of the play description
file here are the answers to some questions:

Q: What if an actor plays several characters?

A: In the [role] command, specify several character= clauses.
The most important character should come first, since it will
be used in the mixer label, which has room for only one character.

Q: How do I handle an actor who appears on stage but does not speak?

A: In the [enter] command, specify the clause speaks=no.  The program
will understand that he does not need a microphone, but because he
is on the stage he cannot be exchanging his microphone with another
actor.

Q: Some of my actors have VIP status: they should not be obliged to
share microphones with anyone.  

A: In the [actor] command, use the clause microphone=<number> to
pre-allocate that microphone to the actor.  List your VIP actors
before other actors.  Microphones will be taken from these actors
only if there are no others available.  To prevent even that, 
modify the timeline so the VIP actors are constantly on stage.

Q: Not all pages of my script have the same running time.  It this
a problem?  If so, how do I fix it?

A: An actor needs a certain time off stage to remove his microphone and
hand it to another actor.  Pages are assumed to be 72 seconds in
length, and two actors need to have half a page off stage together 
(36 seconds) to exchange microphones.  If a page doesn't run 72 seconds, 
you can specify its duration using the [duration <seconds>] command
in the timeline.

Q: Sometimes lots of things happen in the course of a single page.

A: You can divide a page into parts, by appending a letter to
your page numbers: 1a, 1b, 1c, etc, or by appending a number:
1-1, 1-2, etc. or two numbers: 1-1-1, 1-2-1, etc.  I used
page number-measure number in Cats, and page number-song number-measure number
in Jesus Christ Superstar.  By default, the duration of each part is the same,
and the total of the parts of a page is 72 seconds.
However, you can use the [duration <seconds>] command to specify
the time for each part.

Q: How many microphones will I need for my show?

A: Once you have entered your timeline, allocate_microphones will
compute the minimum number of microphones, which is the maximum
number of actors simultaneously on stage who have microphones.

Q: What if I have more microphones than the minimum needed for
the show?

A: If you are in this enviable position, use the [microphone <number>]
command to tell the program how many microphones you have.  The
program will optimize microphone distribution for that many
microphones.  Adding just one or two microphones to the minimum
number needed results in more actors who do not have to share
microphones, more actors who always use the same microphone, and
longer times for microphone exchanges.

Q: I have some actors who sing in small groups.  I have enough
microphones for them, but I want a single slider on the mixing
board which controls their volume, in addition to an individual
slider for each actor.  How do I do this?

A: First, you will need a relatively modern mixing board which
allows several microphones to be routed through a common volume
control slider known as a DCA before they are sent to the speakers.
You can then use the group=<name> clauses to specify that certain
microphones are in the named groups.  You can specify a default group
for a character, and override that whenever the character
enters or begins speaking.  The group name is shown in the
microphone switching section, so you will know into which group
to place each microphone.  You can then assign a volume slider
to each group that you use.

See below for more information on mixers with sequencers.

Q: How do I deal with last-minute changes?

A: Once all the parts are cast, actors can start rehearsing with
microphones, to practice the exchanges.  You may find that some
actors are on stage at unexpected times, for example as part of
the chorus, and that makes some exchanges impractical.  You can
deal with this by modifying the timeline, but this may cause large
changes in the microphone assignments, and you don't want that if
the actors have already learned who their exchange partners are.
Add the existing microphone assignments to the [actor] commands as 
pre-allocations to prevent arbitrary reassignments.  However,
actors should be told when they first rehearse with microphones
that problems found during that rehearsal might result in changes
in the assignments.

Q: The program is doing something wrong, but I can't figure out
how it is failing.

A: I encountered this problem often in development.  You can specify
an additional output file using --trace <file name> which receives
lots of information about how the program is processing its input
file.  Use that file together with the source code for insight on
the internal processing.

Q: What other programs must I install to use this program?

A: You will need Python, version 3 or later, and LaTeX.
With the Ubuntu and Fedora distributions of GNU/Linux,
Python is a standard part of the distribution.
LaTeX and the fonts it needs are also available from the
distribution's package manager.

Q: How do I install the program on my computer?

A: allocate_microphones uses the customary procedure for
installing an application: download the compressed tar file,
uncompress it, use tar to expand it into a subdirectory,
cd into that subdirectory, ./configure, make, sudo make install.
Details are in the INSTALL file.

Q: After I install it, how can I be sure it is working?

A: While in the installation subdirectory, use make check
to process the example shows.  Look in the subdirectories
of the examples directory for the resulting pdf files,
and make sure they print correctly.


Here is the full syntax of the play description file:

[show <showname>] // The name of the show
Venue=<venuename> // Where the show is performed
Designer=<designername> // The name of the person who created this file
		  // other keywords and values are permitted, and are included
		  // in the parameters.tex file.
[microphones <number>]	// the number of microphones available in the theatre
	// if omitted or zero, the program uses the minimum number needed for
	// the show.
[DCA <number>]      // The number of Digitally-Controlled Amplifiers
     		    // on the mixer; default is 8.
style=solo or nosolo // See below for DCA style information
[character <name>]  // information about a character, can be repeated
	   	    // the names must be unique
group=<name>	    // the default group of this character
preferred_DCA=<number>	  // The DCA used by this character, if possible
[group <name>]		  // A group into which characters might move
preferred_DCA=<number>	  // The DCA used by this group, if possible
[actor <name>]  // information about an actor, can be repeated
	// The names must be unique
microphone=<number>	// This actor's microphone number; omit to have
			// the program assign one.
[role]	// assign an actor to a part
actor=<name>	// name of the actor
character=<name>	// Name of a character being played.
			// Can appear more than once, if an actor
			// plays several characters

// Pages are generally numbers, but may also be suffixed with
// a letter or - followed by a number or by two numbers separated by
// a dash or other non-numeric separator to divide a page into parts.  
[page <pageno>]	// The following material pertains to page pageno
prompt=<text>	// The line or action that triggers the cue (page).
//
// The following timeline events happen on the most recent page
// specified.
//
[act <actname>]		// This act begins on this page
     			// <actname> can be prologue, epilogue,
			// a roman numeral or an arabic numeral.
			// an act ends when another act starts
[scene <number>]    	// This scene begins on this page
       			// a scene ends when another scene starts
[duration <number>]	// This page lasts for <number> seconds
	  		// default is 72 seconds, or 1 minute 12 seconds
[song <name>]		// This song is sung on this page
[begin song <name>]	// Start singing this song on this page
[end song <name>]	// Finish singing this song on this page
[sound <name>]		// This sound is heard on this page
[begin sound <name>]	// Start this sound on this page
[end sound <name>]	// Stop this sound on this page
[enter <name>]		// the named character appears on-stage, or is heard
			// off-stage
speaks=no		// the character does not speak during this appearance,
			// hence needs no microphone
group=<name>		// the character is in the named group for this page
[exit <name>]		// the named character leaves the stage, or ceases
			// being heard off-stage
[speak <name>]		// The named character speaks on this page
group=<name>		// the character is in the named group for this page
[speaking <name>]	// The named character speaks until quieted
group=<name>		// the character is in the named group for this page
[quiet <name>]		// The named character stops speaking
[intermission]		// Everyone leaves the stage for about 15 minutes
[end show]		// Everyone leaves the stage until the next performance

Semantic Notes

Assigning an actor a microphone does not guarantee that it will not
be taken away if there are no others available.  Similarly, specifying
a preferred DCA for a character or group does not mean that some other
DCA won't be used if necessary.

Actors early in the actor list have priority over those below them
for keeping their microphones.  Similarly, characters get first choice
of DCAs in the order they are listed, followed by groups in the
order they are listed.  This can be overridden by specifying a
preferred DCA for a group or character.  Characters and groups
with a preferred DCA get first chance at their DCAs.

To facilitate use during early rehearsals, not all characters need
to be cast.  If the actor who is to play a character
is not specified, a unique actor named "Uncast #<number>" is
added to the actor list.  As the show is cast the actual actors
and their rolls can be added and the program re-run to improve 
microphone assignments.  Uncast parts are assumed played by unique 
actors, which is the worst case for allocating microphones.

An actor needs to be off-stage for a minimum of 36 seconds to remove
his microphone.  Likewise, an actor needs to be off-stage for a
minimum of 36 seconds to don his microphone.  The program tries to
have actors don microphones before the show starts and remove them
when it ends, when possible.  When this is not possible, preference
is given to exchanging microphones during intermission.  When this
is also insufficient, microphones are exchanged when actors are
off-stage.  Even in this case, actors will generally keep their
microphones, loaning them to other actors when necessary.

Mixers with DCAs and sequencers.

Mixers with digitally-controlled amplifiers (DCAs) and sequencers have
become affordable.  Allocate_microphones supports two ways of using
these modern mixers: solo and nosolo.

Solo style, which is the default, assigns characters who are not in a group
to DCA channel 0, named Solo.  Groups are spread across the other DCAs so
you can have a volume slider for each active group.  If you wish you can
assign a group to a particular DCA.  Running all the microphones through
the DCAs gives you a more compact control surface for the active microphones.

Nosolo style places characters who are not in a group into DCAs as though
they were in a group named for the character.  All groups and characters
are then spread across the DCAs.  The program attempts to keep groups
and characters in the same DCA whenever they are active.
You can assign groups and characters to DCAs, but they may get moved
to others if needed.  In nosolo style you can choose to define just one
cue per scene and let the mixer operator use the DCA mutes or volume
sliders to control the live microphones within each scene as needed.

If you have a Behringer X32 mixer and the X32 Theatre Control program
to drive it, allocate_microphones outputs an sqlite3 database which
can be loaded into X32 Theatre Control.  X32 Theatre Control will
sequence the mixer and use the scribble strips in the DCAs to say
which group is being controlled.  The documentation for X32 Theatre
Control suggests that the mixer operator will use the DCA sliders
to control microphones between cues, which was the inspiration
for the nosolo style.  

Extended Example

There is a complete example from a show complex enough to need
the services of this program in examples/The_Music_man.
The Amherst PTA produced Merideth Wilson's "The Music Man" in April of 2011.
We had 42 actors who needed microphones, but the theatre could support only
24 microphones.  Early in rehearsal the music director asked people to
volunteer for the 11 solo parts in Wells Fargo Wagon.  To encourage
volunteers I promised that every volunteer would get a microphone.
That promise led to the writing of this program.

In the 2011 production I did not have a mixer with a sequencer
so I dod not use any groups.  To make the mixer operator's job
easier, the first 12 microphones were pre-allocated to the
principals.  The quartet and the featured pick-a-little ladies
were kept together to make operating their mute buttons easier,
and Eulalie was adjacent to both her husband and the featured
pick-a-little ladies.  Assigning a microphone to Mrs. Paroo
was done at the last minute, since the actress was unable to
share a microphone because of her wig.  As a result the wagon driver
and the boy on page 11 did not have microphones.

In 2019 I had a second chance to do The Music Man, this time using
a mixer with a sequencer and DCAs.  I created groups for the
quartet and the pick-a-little ladies, which caused them to be
controlled using a single volume slider.  Rather than use Solo
mode, I created more groups to fit everyone else onto the
eight available DCAs.  The Wells Fargo Wagon soloists have their
own group, as do the unnamed men, women and boys.  The software
tries to allocate each character to the same DCA whenever his
microphone is live.  I let the nameless characters use different
DCAs in different acts, so the named characters would have a
better opportunity to be allocated to the same DCA.  Although
I will have 29 microphones in 2019, the example of The Music Man
shows how to make the show work with only 24 microphones.

The program allocate_microphones is distributed
using the Autotools package.  See the INSTALL file
for details.  The package uses AM_MAINTAINER_MODE,
so if you update the package to use a later
version of the Autotools software, you will need
to use --enable-maintainer-mode when running
the configure script.

The program allocate_microphones was originally written by 
John Sauter in early 2011 to support the Amherst
PTA production of The Music Man.  John Sauter's
contact information is as follows:

John Sauter
System Eyes Computer Store
20A Northwest Blvd.  Ste 345
Nashua, NH  03063-4066
telephone: (603) 424-1188
e-mail: [email protected]