..Help
.Objects
|
File
 |
This multi-function object performs file IO. Modes include Data File, Memory Buffer, Media Reader, Wave Writer, Text Reader and Text Writer. |
| Data File and Mem Buffer
These two modes read and write sample data using shared storage.
|
| io | pin | name | description |
| in | m | move | Trigger tells when to move the file pointer. |
|---|
| sr | sample rate | Specifies how fast to advance the file pointer. Default is one sample per trigger, 44.1KHz. |
| in | s | seek | Trigger tells when to seek to the position at the P input pin. |
|---|
| P | position | Specifies the position to seek to. Default is zero, the beginning. |
| in | w | write | Trigger tells when to write the data. |
|---|
| in | input | Input data to write to the file. |
| out | = | output | Outputs the data at the current file position. |
|---|
| out | P | position | Outputs the current position of the file pointer. |
|---|
| S | size | Outputs the reciprocal of the file size, 1/samples. |
|
For either mode, a file name or ID is required, set these via the popup panel.
In Data File mode you may select an existing .DAT file or create a new one.
In Mem Buffer mode, specify an identifier in the ID box.
All Data Files with the same name and directory are shared.
All Mem Buffers with the same identifier are shared.
A file length is required, also set via the popup panel.
Data File mode uses a .DAT file on the hard disk which may be accessed by multiple file objects and multiple applications.
In order to access the data with another application, the file must be opened in share mode.
The format of the file data is binary 4 byte single precision floating point.
When sharing data between applications there will be synchronization and latency issues,
often on the order of hundreds of milliseconds.
Devising a handshaking scheme can eliminate the synchronization issue, but the latency will remain.
One simplistic handshaking scheme is to assign the first value in the file as a flag and the rest of the file as numeric data.
When one application has finished writing numeric data it can change the sign of the first value to indicate that new data is ready.
The other application can monitor the first value and detect the change of sign.
In the example below,
ArtWonk (algoart.com) writes values to AWonk.dat and ABox reads them.
The lower left Data File reads the first value, used as a flag.
When ArtWonk changes the flag from positive to negative, the upper right Data File seeks and reads the 8th value.
The S size output is used to calculate the seek position.
Both the flag and the 8th value are then used to control the ADSR.
|
Memory Buffer mode uses shared memory and may also be accessed by multiple file objects and multiple instances of ABox2.
Using a memory buffer is far more efficient than the .DAT file but has the following limitations:
1) The size can not exceed 262144 samples, about 6 seconds at 44.1KHz
2) Data is lost forever when all objects using the buffer are destroyed.
3) Assigning more memory than available RAM will wake up the Windows Swap File and degrade system performance.
Both the Data File and the Memory Buffer can be used to build long delay lines.
Memory Buffer is more efficient, but is limited to a maximum of about 6 seconds.
For either object
Set w and m as positive gates and leave them unconnected.
This allows continuous writing and reading.
Turn on loop to make a circular buffer.
The size of the buffer will determine the delay time.
Divide the size by 44100 (or the external sample rate) to determine the loop time.
6 second delay
Memory Buffer mode.
Set file length to maximum.
|
1 hour delay
Data File mode.
You'll need 640MB of disk space to do this.
Set file length to 158,760,000 samples.
|
0 to 1.48 second variable delay
Two Memory Buffers with the same ID.
The size of the buffers determines the maximun delay, in this case 65536/44100 or about 1.48 seconds.
The left buffer writes data, w and m are set to positive gates.
The right buffer reads data using the s seek and P position inputs.
Both buffers are set to normalized position and have loop turned on.
The P position output of the left buffer is subtracted by the desired delay value
and used to set the read position of the right buffer.
The value on the knob may be adjusted from 1.0 (no delay) to 0.0 (maximum delay).
The bottom equation is optional
and converts the value on the knob to an ABox normalized time value.
More taps can be added by duplicating the knob, 2*a equation, subtract object and right Memory Buffer.
To synchronize all the taps, always connect the subtract object to the left buffer's P output.
|
|
| Media Reader
Media Reader mode reads the audio stream from a wide variety of media formats.
|
| io | pin | name | description |
| in | m | move | Trigger tells when to move the file pointer. |
|---|
| sr | sample rate | Specifies how fast to advance the file pointer. Default is specified by the source file. |
| in | s | seek | Trigger tells when to seek to the position at the P input pin. |
|---|
| P | position | Specifies the position to seek to. Default is zero, the beginning. |
| out | L
R | Left Right | Left and Right output data read from the file. |
|---|
| out | P | position | Outputs the current position of the file pointer. |
|---|
| S | size | Outputs the reciprocal of the file size, 1/samples. |
The Media Reader reads most audio and video formats using the DirectShow technology built in to the Microsoft Media Player.
These include .WAV, .MP3, .MPEG, .AVI and possibly many others depending on which codecs are installed on your PC.
An example use of the Media Reader is shown below.
It reads the Tada.wav file and sends it directly to a WaveOut object.
m is set as a positive gate for continuous streaming.
sr could be used to play at different rate.
To replay, use loop or connect to the s seek input.
|
Seeking compressed audio streams is time-consuming.
By default, ABox will not wait for the seeking operation to complete,
sometimes resulting in dropped data from the file.
Use seek sync to force ABox to wait, at the risk of audio drop-outs in the rest of the circuit.
When reading from a video file, you can only seek to key frames.
Video files can not be played backwards,
sr values will be treated as positive numbers.
|
| WAV Writer
The Wave Writer allows you to record a .WAV file at 44100Hz using stereo 16 bit samples.
|
| io | pin | name | description |
| in | w | write | Trigger tells when to write the data. |
|---|
L
R | Left
Right | Left and Right input data. |
| A | amplitude | Optional master volume for the left and right inputs. |
| in | er | erase | Trigger causes the WAV file to be erased and set to zero length. |
|---|
| out | S | size | Outputs the reciprocal of the current file size, 1/samples. |
|---|
The Wave Writer is designed to stream audio data to a WAV file formatted as 44100Hz stereo 16 bits per sample.
This is a write-only mode, thus the move inputs and audio outputs are disabled.
You may create a new wave .wav file or open an existing one.
If the existing file is not 16 bit stereo, ABox will ask if it can erase the data and set the file in the proper format.
The example circuit shown below records the Random and Oscillator output to the wave.wav file.
w is set as positive gate for continuous recording.
It could easily be connected to a button or some other control logic.
The slider connected to the A input acts as a record level control.
|
Writing new data is always appended to the end of the file.
The file length and position will increase automatically.
The .WAV file is created as 44100Hz.
Triggering the w input at a slower rate allows for a lower record rate,
but you will have to change the WAV sample rate manually using an external editor.
To stream continuously, set the w input to gate.
Use a trigger at the er input to erase the file.
CAUTION: erase can not be undone. All previous data will be lost forever.
If another application is currently using the file, ABox may not be able to open it.
ABox will tell you if this happens and allow you to close the other application and press "Retry".
If you press "cancel" and later decide to re-open the file, press the "Filename" button on the popup panel and select the same file.
While the Wave Writer holds ownership of the .wav file,
other applications may not be able to open it and may even report that the file is corrupted.
This is especially true while the file is being recorded.
The file is not corrupted however, merely preoccupied.
When the circuit is stopped, not playing, you may copy the recorded file elsewhere.
This will allow other applications to open and work with the copied file.
|
| Text Reader
Text Reader mode can read a table of numeric data from a text file.
|
| io | pin | name | description |
| in | co
ro | Column
Row | Specifies the column and row to read data from. |
|---|
| in | rr | re-read | Trigger causes the text file to be re-read. |
|---|
| out | = | output | Output data at the current column and row. |
|---|
| out | C
R | cols
rows | Outputs the reciprocal of the number of columns and rows read from the input file. |
|---|
Unlike the other modes, the Text Reader does not require that move or seek operations be performed to read the data.
Instead, the co ro pair of inputs act as position values to read the table data continuously.
Both co and ro may be set to percent or normalized, as described in the position section.
loop mode is also available that causes out of range co ro to wraps around.
The example circuit below shows a Text Reader with knobs to control co and ro inputs.
The file being read is bzero.prn, which was created using MathCad and is a 64 by 64 table of numbers.
The position mode is set to percent, thus the reader is looking at the 12th item of the 32nd row.
|
Also unlike other modes, the Text Reader examines the input file once then closes it.
Other applications can freely change the contents of the input file,
but the changes will not appear to the Text Reader until it is told to re-read the file.
At that time other processes should not be changing the file contents.
The input file must be formatted as ASCII text, 8 bits per character.
Numbers can be stated as integers, decimals or in scientific E notation.
For example: 10, +1.2 and -3.14E-10 are all valid numbers.
If the Text Reader can not figure out what the number is, it will set that cell equal to zero and try to move on.
Columns of numbers can be separated by commas, spaces, tabs, or combination thereof.
Rows are always separated by line feeds.
The Text Reader will always build a rectangular table.
It is not required that table rows be completely filled, once a new line is encountered the rest of the row is set to zero.
The row with the largest number of columns sets the number of columns for the entire table.
It is not required that the input file contain a table.
A single line of numbers results in a table with one row and many columns.
One number per line results in a table with one column and many rows.
Randomly mixed numbers and text may or may not be read as a table.
The reader will usually interpret leading numbers correctly, but it does not hunt for numbers buried in noise.
For example: 123ABC is read as 123.0, but ABC123 is ignored.
|
| Text Writer
Text Writer mode builds a text file with an arbitrary number of rows and columns.
|
| io | pin | name | description |
| in | in | input | Input data to write to the text file. |
|---|
| nc | next column | Trigger writes input data to the current cell and advances the column. |
| nr | next row | Trigger terminates the current row and moves to the first column. Does not write data. |
| in | er | erase | Trigger causes the text file to be erased and reset to zero length. |
|---|
| out | S | size | Outputs the reciprocal of the current file size, 1/values written. |
|---|
The Text Writer has two write triggers: nc next column, and nr next row.
Only the nc trigger writes a text value to the file.
nr only writes a line feed.
To write a single column of numbers, trigger nc and nr at the same time.
To write a single row, only trigger nc.
The example below shows the the Text Writer creating the file rand.txt.
The oscillator causes the Text Reader to write a new number 2 times every second.
The counter causes a new line every 5 values.
Thus the table will have 5 columns of which 19 have already been written.
|
Use a trigger at the er input to erase the file.
CAUTION: erase can not be undone. All previous data will be lost forever.
Format of the output file:
8 bits per character, ASCII text.
Total of 14 characters for numbers.
2 characters for separators.
2 byte linefeeds, 0Dh followed by 0Ah.
+0.000000e+00, -7.669899e-04, +5.882814e+01
Numbers are formatted using scientific E notation:
Leading plus or minus
1 digit, decimal point, 6 digits
e exponent, plus or minus, 2 digits.
A small loss of precision is inherent in the conversion from binary floating point to decimal text.
Usually only in the least significant digit.
For many quantities this conversion is insignificant.
For example, as an amplitude or note value, the difference is imperceptible.
As the seed for a random number generator however, the difference will be noticed immediately.
If absolute accuracy is required, consider using the Data File instead of the Text Writer.
|
| Common Functionality
The File Object transports data to and from the ABox circuit.
For the most part, data is transferred through a file on the hard drive.
To use this object you must:
1) Select a mode. There are six modes, described in the sections above.
2) Select or create a file to work with and possibly set the size of the file.
3) Configure the input triggers to manipulate the file pointer.
The File Pointer
All six modes employ the use of a file pointer.
The file pointer is simply the location of a number inside the file.
The current value of the file pointer is shown on the object as the top number.
The value of the file pointer is not the same as the value of the P position pin,
this is described in the position section.
All access to the file takes place at the location specified by the file pointer.
Some examples:
If the file pointer is 0, you are at the beginning of the file.
If the file pointer is 100, you are one hundred values into the file.
If you want to read one value, you read that value at the location specified by the file pointer.
If you want to write a value, you write that value at the location specified by the file pointer.
If you want to read a lot of values, a stream of samples for example, you read the value at the file pointer,
then move the file pointer and read again, then move the file pointer and read again, ... and so on.
Using the file pointer, there are three basic operations:
1) move to the next position and read the value therein.
2) seek to an arbitrary position and read the value therein.
3) write a value to the current position (and do not move).
Each of the three basic operations is controlled using a trigger input and a parameter input.
The m trigger and the sr sample rate inputs perform the move operation.
The s trigger and the P position inputs perform the seek operation.
The w trigger and the in or L R inputs control the write operation.
The trigger inputs may be set to detect edges or gate levels.
Edge detectors perform the operation once per edge,
while gates perform the operation continuously until the gate goes off.
For Example: If you want to read an audio stream with minimal circuitry,
set the m input to a positive gate and leave the m pin unconnected.
An optional knob connected to the sr sample rate input can control the playback speed.
Not all modes expose all three trigger types however, and some modes rename them.
The mode specific details are described in the sections above.
Seek Write Move Read
The block diagram to the right shows the internal architecture of the File Object.
The 'position' oval is the file pointer.
The 'storage' tank is the file you are working with.
The triangles and inputs represent the controls for the three basic operations: seek, move and write.
The position is updated every sample according to the settings
and values of the m, sr, s and P pins.
Data is read from the file at the new position.
The output data will not change if the position and file data have not changed.
The sequence of operation is seek write move read.
Seek
The s trigger and the P position input can directly control the file pointer and set it to an arbitrary value.
Seeking can only occur when the s input is triggered.
When a trigger event at the s input is received,
the current value at the P position input is read and set as the new file position.
Subsequent write and read operations occur at the new position.
The P position input may be interpreted as either a percentage or as a normalized value.
These are described below in the Position section.
Seek events cancel move events.
If a seek and a move trigger are received at the same time, the seek command is implemented and the move command ignored.
If the s trigger is set to gate mode, move is canceled while the gate is on and the position is constantly updated by the value at the P input pin.
All six modes expose some form of seeking.
Data File, Memory Buffer and Media Reader expose the s trigger and P position input.
Wave Writer and Text Writer expose the seek operation as an er erase operation.
Text Reader implements seek as the rr Re-Read operation.
Seeking from disk files is time consuming, even more so for compressed audio streams.
Excessive seeking results in sluggish response from the user interface and may cause audio dropouts as well.
ABox tries to reduce this by caching and limiting the number of disk reads in a sample frame.
The internal cache is 16KB, disk reads outside of the cache are limited to 16 per frame.
To elaborate:
If you issue 24 seeks in one sample frame (1024 samples)
and the position of each corresponds to data already in the cache,
then no limits take effect and all 24 seeks will complete successfully.
If, however, none of the 24 seek positions correspond to cached data,
then only the first 16 seeks will complete successfully, the remaining 8 will be ignored.
Note that above only applies to disk files.
The Memory Buffer does not have seeking limits.
The Media Reader by default does not wait for seeking operations to complete.
You may over-ride this by using seek sync, which may cause audio dropouts.
Write
The w trigger input controls the write operation.
When a trigger event is received at w,
the current value of the in input pin is read
and sent to the disk file at the current position of the file pointer.
There are differences in how each mode handles the write operation:
Media Reader and Text Reader do not implement the write operation.
Data File and Memory buffer expose the w and in pins.
Writing in these modes does not change the file position.
Wave Writer exposes the w and L R inputs.
Writing in this mode is always at the end of the file, which will grow automatically.
Text Writer exposes two write triggers nc next column and nr next row.
Writing in this mode is always at the end of the file, which will grow automatically.
Move and Sample Rate
Moving changes the file pointer by adding a number to its current value.
Unlike seek, which can set the file pointer to any value,
move can only change it by a small amount, usually one sample.
The m input trigger controls the move operation.
When an m trigger event is received,
the current value at the sr sample rate input is added to the file pointer.
Subsequent read and write operations take place at the new position.
By default, when the file pointer reaches the end of the file it stays there and no further reads or writes can occur.
Override this by using the loop setting, which automatically rewinds to the beginning of the file and all continues as normal.
The sr sample rate controls how far the file pointer is moved at each m trigger event.
If sr is not connected, it defaults to one sample, which corresponds to 44100 samples per seconds.
The Media Reader, however, overrides the default sample rate by setting it to the sample rate specified by the source material.
Specify a different sample rate by connecting a value to the sr pin.
The value at the sr pin is displayed as two times the frequency.
Data File and Memory Buffer mode allows negative sample rates, resulting in reverse playback.
The Media Reader does not allow backwards playback and negative values are converted to positive.
Sample rate distortion will be heard when playing at slower speeds.
This can be reduced by using one or more low pass filters on the output.
Set the filter cutoff frequency at one half the sample rate.
Or simply use the same value applied to the sr pin, or a slightly lower value.
Using LP filters in this manner is called anti-aliasing.
Read
After some combination of the seek write move operations are completed, data is read from the file and sent to the output pins.
This happens automatically, there are no special actions needed to read data.
Position
The location of the file pointer can be specified in one of two ways:
Percent: P is a number between 0 and 1, 0 is the beginning of the file, 1 is the end.
Negative numbers are converted to positive, thus -1 also corresponds to the end of the file.
Percent mode is an intuitive way of specifying file locations.
For example, if want to jump one quarter into the file, simply set P as 0.25.
Normalized: P is a number between -1 and +1.
-1 is the beginning of the file, +1 is the end.
0.0 is the half way through the file.
Normalized mode is useful for scanning through a file using an oscillator.
For example, a ramp wave connected to the P input will scan through the whole file.
There may be two P position pins on the File Object.
One of them is an input used for seeking.
The other is an output pin used for monitoring the file pointer.
Both input and output pins share the same format.
In loop mode, out of range P values are wrapped around the file.
This will have different behavior depending on whether P is a percent or normalized.
For example, if P is -2.5:
In percent mode the wrapped position is 0.5, or half way through the file.
0.0 is the beginning of the file.
-2.5 is converted to +2.5.
+2 times around the file, still at the beginning.
Then half around.
In normalized mode the wrapped position is -0.5, one quarter into the file.
0.0 is half way into the file.
-2 correspond to one time around the file.
Still at position 0, half way into the file.
-0.5 is one quarter back from half.
Size
All modes have some form of a S size output pin.
The value at the S pin is the reciprocal of the number of samples in the file.
1/number of samples.
The reciprocal is used to prevent enormous numbers inside the circuit.
Instead they are converted to very small numbers.
For example, if the file size 10MB, the S pin will report 1.0e-7.
If the file is empty, size equal to zero, the S pin will report 1.0.
|
|