Classes | GUI > Views

SoundFileView : View : QObject : Object

Sound file display
Subclasses: QSoundFileView

Description

A sound file viewer with numerous options.

Zoom in and out using Shift + right-click + mouse-up/down;

Scroll using right-click + mouse-left/right.

Class Methods

Inherited class methods

Undocumented class methods

SoundFileView.qtClass

Instance Methods

Data

.soundfile

.soundfile = value

Arguments:

(arg1)

An Instance of SoundFile to display.

.read(startFrame, frames, block, closeFile, doneAction)

Reads a section of the -soundfile and displays it in the view. For large files, you may want to use readWithTask instead.

The 'block' argument has no effect; the display resolution is infinite.

Arguments:

startFrame

The beginning of the section, in frames.

frames

The size of the section, in frames.

block

The block size - visual resolution of the display. An Integer of the form 2**n.

closeFile

If true, closes the SoundFile after reading.

doneAction

A Function called when the file reading has completed.

.readFile(aSoundFile, startFrame, frames, block, closeFile, doneAction)

Reads a section of an open instance of SoundFile, and displays it in the view. For large files, you may want to use the method readWithTask instead.

The 'block' argument has no effect; the display resolution is infinite.

Arguments:

aSoundFile

An open instance of SoundFile.

startFrame

The beginning of the section, in frames.

frames

The size of the section, in frames.

block

The block size - visual resolution of the display. An Integer of the form 2**n.

closeFile

If true, closes the SoundFile after reading.

doneAction

A Function called when the file reading has completed.

.readWithTask(startFrame, frames, block, doneAction, showProgress)

Reads a section of the -soundfile asynchronously (in the background), updating the -readProgress along the way. If the showProgress argument is true, a SoundFileViewProgressWindow opens to show the progress.

The 'block' argument has no effect; the display resolution is infinite. The 'showProgress' argument has no effect; the view always displays reading progress within itself.

Arguments:

startFrame

The beginning of the section, in frames.

frames

The size of the section, in frames.

block

The block size - visual resolution of the display. An Integer of the form 2**n.

doneAction

An optional function to be evaluated on completion.

showProgress

Whether to open a progress window. Defaults to true.

.readFileWithTask(soundFile, startFrame, frames, block, doneAction, showProgress)

Reads a section of an open instance of SoundFile asynchronously (in the background), updating the -readProgress along the way. If the showProgress argument is true, a SoundFileViewProgressWindow opens to show the progress.

The 'block' argument has no effect; the display resolution is infinite. The 'showProgress' argument has no effect; the view always displays reading progress within itself.

Arguments:

soundFile

An open instance of SoundFile.

startFrame

The beginning of the section, in frames.

frames

The size of the section, in frames.

block

The block size - visual resolution of the display. An Integer of the form 2**n.

doneAction

An optional function to be evaluated on completion.

showProgress

Whether to open a progress window. Defaults to true.

.data = data

Gets the display data, or sets custom data instead of a sound file.

It is not possible to get the data.

Setting this property assumes 1 channel and sample rate of 44100 Hz. Use -setData instead if you want more control.

Arguments:

data

An Array of Floats; multiple channel data should be interleaved.

.setData(data, block, startFrame: 0, channels: 1, samplerate: 44100)

Sets custom display data instead of a sound file, interpreting it using specified number of channels and sample rate.

Arguments:

data

An Array of Floats; multiple channel data should be interleaved.

block

The block size - visual resolution of the display. An Integer of the form 2**n. (since the port to QT, the 'block' argument has no effect; the display resolution is infinite).

startFrame

An integer.

channels

An integer.

samplerate

An integer.

.alloc(frames, channels: 1, samplerate: 44100)

Allocates a desired amount of display channels and frames; all frames have initial value of 0.

Arguments:

frames

An Integer.

channels

An Integer.

samplerate

An Integer.

.set(offset: 0, data)

Overwrites a range of display data with another data. This method can be used after -alloc or -setData has been called, but not while the view is displaying a sound file.

Arguments:

offset

The frame at which to start overwriting; an Integer.

data

The new data; an Array of Floats; multiple channel data should be interleaved.

.startFrame

The beginning of the read section of the soundfile, or 0 if -alloc or -setData has been used.

.numFrames

The total amount of frames in the view; this is unrelated to zooming and scrolling.

.readProgress

The reading progress, updated periodically when reading a soundfile using -readWithTask or -readFileWithTask.

Navigation

.viewFrames

The amount of currently visible frames in the view.

.zoom(factor)

Zooms by a factor relative to current zoom.

Arguments:

factor

A Float.

.zoomToFrac(fraction)

Zooms to a specific scale.

Arguments:

fraction

A Float.

.zoomAllOut

Zooms to the current selection.

.zoomSelection(selection)

Zooms to a specific selection.

Arguments:

selection

The index of the selection; an Integer between 0 an 63.

.scrollPos

The scrolling position of the view, as a fraction of the total scrolling range.

Returns:

A Float in the range of 0.0 to 1.0.

.scrollTo(fraction)

Scrolls to a fraction of the total scrolling range.

Arguments:

fraction

A Float in the range of 0.0 to 1.0.

.scroll(fraction)

Scrolls by a fraction of the visible range.

Arguments:

fraction

A Float.

.scrollToStart

Scrolls to the beginning.

.scrollToEnd

Scrolls to the end.

Selection

.selections

All the selections.

Returns:

An array of 64 arrays of start frames and sizes: [ [ start0, size0 ] , [ start1, size1 ], ... ].

.selection(index)

The selection at index.

Returns:

An Array of the form [start, size], where start and size denote frames.

.setSelection(index, selection)

Sets the selection at index.

Arguments:

index

An Integer between 0 an 63.

selection

An Array of the form [start, size], where start and size are Integers and denote frames.

.currentSelection

.currentSelection = index

The index of the current selection

Arguments:

index

An integer between 0 an 63.

.selectionStart(index)

The start frame of a selection.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

Returns:

An Integer.

.setSelectionStart(index, frame)

Sets the start frame of a selection.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

frame

The starting frame of the selection, an Integer.

.selectionSize(index)

The size of a selection.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

Returns:

An Integer.

.setSelectionSize(index, frames)

Sets the size of a selection.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

frames

The size in frames of the selection, an Integer.

.selectionStartTime(index)

The start of a selection in seconds.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

Returns:

A Float.

.selectionDuration(index)

The size of a selection in seconds.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

Returns:

A Float.

.selectAll(index)

Sets a selection to span the whole data range.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

.selectNone(index)

Sets the size of a selection to 0.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

.setSelectionColor(index, color)

Sets the color of a selection.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

color

A Color.

.setEditableSelectionStart(index, editable)

Sets whether the start point of a selection can be edited.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

editable

A Boolean.

.setEditableSelectionSize(index, editable)

Whether the end point of a selection can be edited.

Arguments:

index

The index of the selection; an Integer between 0 an 63.

editable

A Boolean.

.readSelection(block, closeFile)

NOTE: Not implemented

Read the data within a selection.

Arguments:

block

The block size - visual resolution of the display. An Integer of the form 2**n.

closeFile

If true, closes the SoundFile after reading.

.readSelectionWithTask

NOTE: Not implemented

Read the data within the current selection asynchronously (in the background), showing the progress in a separate window.

Display

.gridOn

.gridOn = flag

Whether the grid is displayed. Defaults to true.

Arguments:

flag

A Boolean.

.gridResolution

.gridResolution = seconds

The resolution of the grid.

Arguments:

seconds

An instance of Float.

.gridOffset

.gridOffset = seconds

Sets the grid offset.

Arguments:

seconds

Grid blocks are offset by this value (in seconds).

.gridColor

.gridColor = color

The color of the grid.

Arguments:

color

A Color.

.drawsWaveForm

.drawsWaveForm = boolean

Whether the data is displayed. Defaults to true.

Arguments:

boolean

A Boolean.

.timeCursorOn

.timeCursorOn = flag

Whether the time cursor is displayed. Defaults to false.

Arguments:

flag

A Boolean.

.timeCursorPosition

.timeCursorPosition = frame

The position of the time cursor in frames.

Arguments:

frame

An Integer.

.timeCursorColor

.timeCursorColor = color

The color of the time cursor.

Arguments:

color

A Color.

.elasticMode

.elasticMode = value

???

Actions

.action

.action = func

From superclass: View

The object to be evaluated whenever the user interacts with the view.

.metaAction

.metaAction = action

The object to be evaluated on Ctrl + click.

Inherited instance methods

Undocumented instance methods

.load(filename, startFrame, frames, block, doneAction)

.peakColor

.peakColor = color

.rmsColor

.rmsColor = color

.timeCursorEditable

.timeCursorEditable = flag

.waveColors

.waveColors = colors

.xZoom

.xZoom = seconds

.yZoom

.yZoom = factor

Examples

Basic example

// To zoom in/out: Shift + right-click + mouse-up/down
// To scroll: right-click + mouse-left/right
(
w = Window.new("soundfile test", Rect(200, 300, 740, 100));
a = SoundFileView.new(w, Rect(20,20, 700, 60));

f = SoundFile.new;
f.openRead(Platform.resourceDir +/+ "sounds/a11wlk01.wav");
f.inspect;

a.soundfile = f;
a.read(0, f.numFrames);
a.elasticMode = true;

a.timeCursorOn = true;
a.timeCursorColor = Color.red;
a.timeCursorPosition = 2050;
a.drawsWaveForm = true;
a.gridOn = true;
a.gridResolution = 0.2;

w.front;
)

Step by step examples

( // make a simple SoundFileView
y = Window.screenBounds.height - 120;
w = Window.new("soundfile test", Rect(200, y, 740, 100)).alwaysOnTop_(true);
w.front;
a = SoundFileView.new(w, Rect(20,20, 700, 60));

f = SoundFile.new;
f.openRead(Platform.resourceDir +/+ "sounds/a11wlk01.wav");
// f.inspect;

a.soundfile = f;            // set soundfile
a.read(0, f.numFrames);     // read in the entire file.
a.refresh;                  // refresh to display the file.
)

// To zoom in/out: Shift + right-click + mouse-up/down
// To scroll: right-click + mouse-left/right

// reading file
a.read(0, f.numFrames / 2).refresh; // read first half
a.read.refresh;                     // read entire file by default
a.read(f.numFrames / 2).refresh;    // read second half
a.read(0, -1).refresh;              // -1 also reads entire file, like buffer.

// the resolution of the view is always infinite;
// you can always zoom in until you see a single sample.

a.read(0, -1).refresh;

// for longer files, you can use:
a.readWithTask;

// zoom is relative
a.zoom(0.2).refresh;
a.zoom(2).refresh;
a.zoom(2).refresh;
a.zoomToFrac(0.5); // zoom to half file size
a.zoomAllOut;

a.gridOn = true;            // time grid, 1 second by default,
a.gridResolution = 0.2;     // or set resolution in seconds
a.gridColor = Color.cyan;   // color is changeable.
a.gridOffset_(0.1);         // not sure if this is working?

a.timeCursorOn = true;          // a settable cursor
a.timeCursorPosition = 2050;    // position is in frames.
a.timeCursorColor = Color.white;

// toggle drawing on/off
a.drawsWaveForm = false;
a.drawsWaveForm = true;

// these methods should return view properties:
a.gridOn
a.gridResolution
a.gridColor
a.timeCursorOn
a.timeCursorPosition
a.timeCursorColor

// Selections: multiple selections are supported.
// e.g. use selection 0:
a.setSelectionColor(0, Color.red);  // set...( index, value )
a.selectionStart(0);                // at index
a.setSelectionStart(0, 12345);
a.setSelectionSize(0, 12345);

a.setSelectionStart(0, 1234);
a.selectionStart(0);

// now selection 1
a.setSelectionColor(1, Color.white);
a.setSelectionStart(1, 1234).setSelectionSize(1, 1234 * 2);
a.selectionStart(1);
a.setSelectionStart(0, 12345);

// the current selection gets changed when click/dragging in view.
a.currentSelection;     // index of current selection;
a.currentSelection_(1); // switch current selection - try click/drag white now.
a.currentSelection;

a.selections.size;      // 64 selections
a.selections[0];
a.selections[1];
a.selections;

// setSelection (index, selection);
a.setSelection(0, [234, 2345]);
a.selection(1); // returns [start, size].


a.elasticMode = true;   // not sure if this is working yet?

(       // mouseUpAction
a.mouseUpAction = {
    ("mouseUp, current selection is now:"
        + a.selections[a.currentSelection]).postln;
};
)
// lock selection 0:
a.currentSelection_(0);
a.setEditableSelectionStart(0, false);
a.setEditableSelectionSize(0, false);


// unlock selection 0:
a.setEditableSelectionStart(0, true);
a.setEditableSelectionSize(0, true);

a.selectionStartTime(0);
a.selectionDuration(0);


a.setSelectionStart(0, 12345);
a.setSelectionSize(0, 12345);
a.readSelection.refresh;
a.readSelection(16).refresh;    // in higher resolution
a.read.refresh;                 // go back to entire file.


a.dataNumSamples;   // visual data have this many points
a.data.plot;
a.setData(a.data.reverse);


a.zoom(0.25);       // scrolling is normalized
a.scrollTo(0.5);    //
a.scrollTo(0.6);    //
a.scroll(12);       // scroll is in viewFrames.

a.zoom(4);

w.close;