Technical Writing Sample: Joseph Zitt Samples of documentation for audio processing modules created with the PD graphical audio programming language. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Name Purpose improvoice Processes an audio input by shifting its pitch and adding delays as specified by live interaction. Description The improvoice patch was developed to process live vocal improvisation, with an eye toward ease of use and flexibility as well as minimizing the amount of computer processing needed. All interaction is done via a mouse. (In the initial performances, a handheld pointer device was used instead of a mouse, leaving the performer free to gesture without needing contact with a keyboard.) The audio signal, passed into the computer via an A/D converter, first flows through the shift-multiply patch, which shifts the pitch of the signal by a just-intoned interval as set by the shiftdirection and shiftamount controls. A blender patch then mixes the pitch-shifted signal and the original unshifted signal, with the proportions set by the shiftmix control. The mixed signal then flows into the delayer patch containing four separate delays of differing lengths, with its input volume set by an inputcontrol control and the amount of delayed signal fed back into the delays set by the loopcontrol control. Another blender patch mixes the output of the delayer patch with the undelayed signal, with the proportions set by the delaymix control. The mixed signal is then fed through a high-pass filter set to a very low frequency (which cleans some system noise from the sound) then out through the D/A converter, with the output level determined by the fadecontrol control. Inlets Order Type Description 1 adc~ Audio signal from A/D converter Outlets Order Type Description 1 dac~ Signal sent to D/A converter User interface controls Name Description shiftdirection Direction of pitch shift Controls Type Value Result Message 1 Pitches are shifted upward. Message -1 Pitches are shifted downward. Name Description shiftamount Amount of pitch shift, by just-intoned intervals. If the shiftdirection control is set to "1", pitches are shifted upward by the intervals shown for each message control. If the shiftdirection control is set to "-1", pitches are shifted to an octave below the pitch to which they are when it is set to "1", with two exceptions: if the shiftamount control is set to "0", the pitch is not shifted in either direction; if the shiftamount control is set to "1", the pitch is shifted up by one octave if the shiftdirection control is set to "1" and down by one octave if the shiftdirection control is set to "-1". Controls Type Value Result Message 0 No shift Message 1 2/1 Octave Message 2 3/2 Perfect fifth Message 3 4/3 Perfect fourth Message 4 5/4 Major third Message 5 6/5 Minor third Message 6 7/6 Septimal minor third Message 7 8/7 Septimal whole tone Message 8 9/8 Major whole tone Message 9 10/9 Minor whole tone Message 10 11/10 (unnamed) Message 11 12/11 Median second Message 12 13/12 (unnamed) Name Description shiftmix Determines the blend between the pitch-shifted and unshifted signals. Controls Type Value Result Message 0 Unshifted signal only Message 0 1000 Change to unshifted signal only over one second Message 50 Even balance of pitch-shifted and unshifted signal Message 50 1000 Change to even balance between pitch-shifted and unshifted signal over one second Message 100 1000 Change to pitch-shifted signal only over one second Message 100 Pitch shifted signal only Number 0-100 Slides between integer values from unshifted signal only (0) to pitch-shifted signal only (100) Name Description inputcontrol Determines the volume of signal fed into the delayer patch Controls Type Value Result Message 0 No signal Message 0 1000 Fade out input over one second Message 100 1000 Fade up to full volume over one second Message 100 Full volume Number 0-100 Slides between integer values from no signal to full volume Name Description loopcontrol Determines the percentage of feedback in the delayer patch Controls Type Value Result Message 0 No delay Message 0 1000 Change to no delay over one second Message 99 1000 Change to maximum delay feedback over one second Message 99 Maximum delay feedback Number 0-99 Slides between integer values from no delay to maximum Name Description delaymix Determines the blend between the original and delayed signals Controls Type Value Result Message 0 Original signal only Message 0 1000 Change to original signal only over one second Message 50 Even balance of delayed and original signal Message 50 1000 Change to even balance between delayed and original signal over one second Message 100 1000 Change to delayed signal only over one second Message 100 Delayed signal only Number 0 100 Slides between integer values from original signal only (0) to delayed signal only (100) Name Description fadecontrol Determines the output volume Controls Type Value Result Message 0 Silence Message 0 1000 Fade down to silence over one second Message 99 1000 Fade up to full volume over one second Message 99 Full volume Number 0-99 Slides betwen integer values from silence to full volume Other patches called blender delayer shift-multiply - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Name Purpose blender Mixes two audio signals. Description A numeric control inlet determines the balance between the signals. For example, when the control value is set to "75" the blender patch attenuates the first signal to 75% of its incoming strength and attenuates the second signal to 25% of its incoming strength, returning the mixed signal at the signal outlet. Inlets Order Type Description 1 Signal First audio signal 2 Signal Second audio signal 3 Control Number 0-100 Controls the mix of the first and second signal. The number indicates the percentage of the first signal in the mixed output. The percentage of the second signal is 100 minus the control value. Outlets Order Type Description 1 Signal Mixed audio signal User interface controls None Other patches called None - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Name Purpose delayer Sends audio signal through a series of looping delays Description This patch uses a set of four delays, with delay times of 1000, 1010, 1015, and 1025 milliseconds. Each delay sends its output to the patch's signal output and feeds its output back into itself, attenuated to the percentage of its output value determined by the control inlet. For example, a control value of "75" causes the output of each delay to be fed into itself at 75% of its output strength each times. The control value affects the number of repeats exponentially: For example, when the control value is set to "50", the signal is attenuated to 50% of its original strength when first fed back in, 25% the second time, 12.5% the third time, and thus disappears rather quickly. When the control value is set to "99", the signal is fed back in at 99% the first time, 98.01% the second time, 97.03% the third time, and fades away much more slowly. You can clear the delays instantly by setting the control value to "0", or clear it quickly but more gradually by setting it to a value below "20". Due to the very close but varied delay times, input signals with gradual envelopes tend to smooth out into steady washes of sound. Sharp attacks or decays result in phasing rhythmic patterns, reminiscent of the early music of Steve Reich. Inlets Order Type Description 1 Signal Incoming audio signal 2 Control Number (Range: 0-99) Percentage of signal fed into delay on each repeat Outlets Order Type Description 1 Signal Outgoing audio signal User interface controls None Other patches used None - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Name Purpose shift-multiply Shifts the pitch of a signal by an indicated ratio Description This patch, derived from the "56.delay.pitchshift.pd" pitch shifter supplied with the PD documentation, shifts the frequency of an incoming signal according to a control value. If the control value is positive, the patch shifts the frequency by the ratio of n/(n-1) where n is the control value. For example, a control value of "3" shifts the frequency by a ratio of 3/2 (a just-intoned perfect fifth above the frequency of the incoming signal). If the control value is negative, the patch shifts the frequency by the ratio of n/n+1 where n is the absolute value of the control value. For example, a control value of "-3" shifts the frequency by 3/4 (a just-intoned perfect fourth below the frequency of the incoming signal). If the control value is zero, the incoming signal is passed through unaltered. While the patch can accept non-integer control values, integer values provide simpler and clearer pitch relationships. Inlets Order Type Description 1 Signal Incoming audio signal 2 Control Determines ratio of pitch shifting Outlets Order Type Description 1 Signal Outgoing pitch shifted audio User interface controls None Other patches used None