HelpSource/Classes/SoundFileView.schelp

   1 class:: SoundFileView
   2 redirect:: implClass
   3 summary:: Sound file display
   4 categories:: GUI>Views
   5 related:: Classes/SoundFile
   6
   7
   8 DESCRIPTION::
   9
  10 A sound file viewer with numerous options.
  11
  12
  13 CLASSMETHODS::
  14
  15 PRIVATE:: key
  16
  17
  18 INSTANCEMETHODS::
  19
  20 SUBSECTION:: Data
  21
  22 METHOD:: soundfile
  23
  24     argument::
  25         An Instance of SoundFile to display.
  26
  27
  28 METHOD:: read
  29
  30     Reads a section of the link::#-soundfile:: and displays it in the view. For large files, you may want to use readWithTask instead.
  31
  32     note:: In Qt GUI, the 'block' argument has no effect; the display resolution is infinite. ::
  33
  34     argument:: startFrame
  35         The beginning of the section, in frames.
  36
  37     argument:: frames
  38         The size of the section, in frames.
  39
  40     argument:: block
  41         The block size - visual resolution of the display. An Integer of the form 2**n.
  42
  43     argument:: closeFile
  44         If true, closes the SoundFile after reading.
  45
  46
  47 METHOD:: readFile
  48
  49     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.
  50
  51     note:: In Qt GUI, the 'block' argument has no effect; the display resolution is infinite. ::
  52
  53     argument:: soundfile
  54         An open instance of SoundFile.
  55
  56     argument:: startFrame
  57         The beginning of the section, in frames.
  58
  59     argument:: frames
  60         The size of the section, in frames.
  61
  62     argument:: block
  63         The block size - visual resolution of the display. An Integer of the form 2**n.
  64
  65     argument:: closeFile
  66         If true, closes the SoundFile after reading.
  67
  68 METHOD:: readWithTask
  69
  70     Reads a section of the link::#-soundfile:: asynchronously (in the background), updating the link::#-readProgress:: along the way. If the code::showProgress:: argument is code::true::, a SoundFileViewProgressWindow opens to show the progress.
  71
  72     note:: In Qt GUI:
  73         The 'block' argument has no effect; the display resolution is infinite.
  74         The 'showProgress' argument has no effect; the view always displays reading progress within itself.
  75     ::
  76
  77     argument:: startFrame
  78         The beginning of the section, in frames.
  79
  80     argument:: frames
  81         The size of the section, in frames.
  82
  83     argument:: block
  84         The block size - visual resolution of the display. An Integer of the form 2**n.
  85
  86     argument:: doneAction
  87         An optional function to be evaluated on completion.
  88
  89     argument:: showProgress
  90         Whether to open a progress window. Defaults to code::true::.
  91
  92
  93 METHOD:: readFileWithTask
  94
  95     Reads a section of an open instance of SoundFile asynchronously (in the background), updating the link::#-readProgress:: along the way. If the code::showProgress:: argument is code::true::, a SoundFileViewProgressWindow opens to show the progress.
  96
  97     note:: In Qt GUI:
  98         The 'block' argument has no effect; the display resolution is infinite.
  99         The 'showProgress' argument has no effect; the view always displays reading progress within itself.
 100     ::
 101
 102     argument:: soundfile
 103         An open instance of SoundFile.
 104
 105     argument:: startFrame
 106         The beginning of the section, in frames.
 107
 108     argument:: frames
 109         The size of the section, in frames.
 110
 111     argument:: block
 112         The block size - visual resolution of the display. An Integer of the form 2**n.
 113
 114     argument:: doneAction
 115         An optional function to be evaluated on completion.
 116
 117     argument:: showProgress
 118         Whether to open a progress window. Defaults to code::true::.
 119
 120 METHOD:: startFrame
 121
 122     The beginning of the displayed section of the soundfile, in frames.
 123
 124 METHOD:: numFrames
 125
 126     The size of the displayed section of the soundfile, in frames.
 127
 128 METHOD:: readProgress
 129
 130      The reading progress, updated periodically when reading a soundfile using link::#-readWithTask:: or link::#-readFileWithTask::.
 131
 132 METHOD:: data
 133
 134     Gets the display data, or sets custom data instead of a sound file.
 135
 136     note:: In Qt and SwingOSC it is not possible to get the data. ::
 137
 138     In Cocoa and SwingOSC, setting this property is equivalent to link::#-setData:: with number of channels and sample rate of the current link::#-soundfile:: (if any), while in Qt it always assumes 1 channel and sample rate of 44100 Hz. Use link::#-setData:: instead if you want more control.
 139
 140     argument::
 141         An Array of Floats; multiple channel data should be interleaved.
 142
 143 METHOD:: setData
 144
 145     Sets custom display data instead of a sound file, interpreting it using specified number of channels and sample rate.
 146
 147     note:: In Qt GUI, the 'block' argument has no effect; the display resolution is infinite. ::
 148
 149     argument:: arr
 150         An Array of Floats; multiple channel data should be interleaved.
 151
 152     argument:: block
 153         The block size - visual resolution of the display. An Integer of the form 2**n.
 154
 155     argument:: startframe
 156         An integer.
 157
 158     argument:: channels
 159         An integer.
 160
 161     argument:: samplerate
 162         An integer.
 163
 164
 165 SUBSECTION:: Navigation
 166
 167 METHOD:: viewFrames
 168
 169     The amount of currently visible frames in the view.
 170
 171 METHOD:: zoom
 172
 173     Zooms by a factor relative to current zoom.
 174
 175     argument::
 176         A Float.
 177
 178 METHOD:: zoomToFrac
 179
 180     Zooms to a specific scale.
 181
 182     argument::
 183         A Float.
 184
 185 METHOD:: zoomAllOut
 186
 187     Zooms to the link::#-currentSelection#current selection::.
 188
 189 METHOD:: zoomSelection
 190
 191     Zooms to a specific selection.
 192
 193     argument::
 194         The index of the selection; an Integer between 0 an 63.
 195
 196 METHOD:: scrollPos
 197
 198     The scrolling position of the view, as a fraction of the total scrolling range.
 199
 200     returns::
 201         A Float in the range of 0.0 to 1.0.
 202
 203 METHOD:: scrollTo
 204
 205     Scrolls to a fraction of the total scrolling range.
 206
 207     argument::
 208         A Float in the range of 0.0 to 1.0.
 209
 210 METHOD:: scroll
 211
 212     Scrolls by a fraction of the visible range.
 213
 214     argument::
 215         A Float.
 216
 217 METHOD:: scrollToStart
 218
 219     Scrolls to the beginning.
 220
 221 METHOD:: scrollToEnd
 222
 223     Scrolls to the end.
 224
 225
 226 SUBSECTION:: Selection
 227
 228 METHOD:: selections
 229
 230     All the selections.
 231
 232     returns:: An array of 64 arrays of start frames and sizes: [ [ start0, size0 ] , [ start1, size1 ], ... ].
 233
 234 METHOD:: selection
 235
 236     The selection at index.
 237
 238     returns::
 239         An Array of the form code::[start, size]::, where start and size denote frames.
 240
 241 METHOD:: setSelection
 242
 243     Sets the selection at index.
 244
 245     argument:: index
 246         An Integer between 0 an 63.
 247
 248     argument:: selection
 249         An Array of the form code::[start, size]::, where start and size are Integers and denote frames.
 250
 251 METHOD:: currentSelection
 252
 253     The index of the current selection
 254
 255     argument::
 256         An integer between 0 an 63.
 257
 258 METHOD:: selectionStart
 259
 260     The start frame of a selection.
 261
 262     argument:: index
 263         The index of the selection; an Integer between 0 an 63.
 264
 265     returns::
 266         An Integer.
 267
 268 METHOD:: setSelectionStart (index, frame)
 269
 270     Sets the start frame of a selection.
 271
 272     argument:: index
 273         The index of the selection; an Integer between 0 an 63.
 274
 275     argument:: frame
 276         The starting frame of the selection, an Integer.
 277
 278 METHOD:: selectionSize
 279
 280     The size of a selection.
 281
 282     argument:: index
 283         The index of the selection; an Integer between 0 an 63.
 284
 285     returns::
 286         An Integer.
 287
 288 METHOD:: setSelectionSize
 289
 290     Sets the size of a selection.
 291
 292     argument:: index
 293         The index of the selection; an Integer between 0 an 63.
 294
 295     argument:: frames
 296         The size in frames of the selection, an Integer.
 297
 298 METHOD:: selectionStartTime
 299
 300     The start of a selection in seconds.
 301
 302     argument:: index
 303         The index of the selection; an Integer between 0 an 63.
 304
 305     returns::
 306         A Float.
 307
 308 METHOD:: selectionDuration
 309
 310     The size of a selection in seconds.
 311
 312     argument:: index
 313         The index of the selection; an Integer between 0 an 63.
 314
 315     returns::
 316         A Float.
 317
 318 METHOD:: selectAll
 319
 320     Sets a selection to span the whole data range.
 321
 322     argument:: index
 323         The index of the selection; an Integer between 0 an 63.
 324
 325
 326 METHOD:: selectNone
 327
 328     Sets the size of a selectino to 0.
 329
 330     argument:: index
 331         The index of the selection; an Integer between 0 an 63.
 332
 333 METHOD:: setSelectionColor
 334
 335     Sets the color of a selection.
 336
 337     argument:: index
 338         The index of the selection; an Integer between 0 an 63.
 339
 340     argument:: color
 341         A Color.
 342
 343 METHOD:: setEditableSelectionStart
 344
 345     Sets whether the start point of a selection can be edited.
 346
 347     argument:: index
 348         The index of the selection; an Integer between 0 an 63.
 349
 350     argument:: editable
 351         A Boolean.
 352
 353 METHOD:: setEditableSelectionSize (index, bool)
 354
 355     Whether the end point of a selection can be edited.
 356
 357     argument:: index
 358         The index of the selection; an Integer between 0 an 63.
 359
 360     argument:: editable
 361         A Boolean.
 362
 363 METHOD:: readSelection
 364
 365     note:: Not in Qt GUI ::
 366
 367     Read the data within a selection.
 368
 369     argument:: block
 370         The block size - visual resolution of the display. An Integer of the form 2**n.
 371
 372     argument:: closeFile
 373         If true, closes the SoundFile after reading.
 374
 375 METHOD:: readSelectionWithTask
 376
 377     note:: Not in Qt GUI ::
 378
 379     Read the data within the current selection asynchronously (in the background), showing the progress in a separate window.
 380
 381
 382 SUBSECTION:: Display
 383
 384 METHOD:: gridOn
 385
 386     Whether the grid is displayed. Defaults to code::true::.
 387
 388     argument::
 389         A Boolean.
 390
 391 METHOD:: gridResolution
 392
 393     The resolution of the grid.
 394
 395     argument::
 396         An instance of Float.
 397
 398 METHOD:: gridOffset
 399
 400     Sets the grid offset.
 401
 402     argument::
 403         An integer.
 404
 405 METHOD:: gridColor
 406
 407     The color of the grid.
 408
 409     argument::
 410         A Color.
 411
 412 METHOD:: drawsWaveForm
 413
 414     Whether the data is displayed. Defaults to code::true::.
 415
 416     argument::
 417         A Boolean.
 418
 419 METHOD:: timeCursorOn
 420
 421     Whether the time cursor is displayed. Defaults to code::false::.
 422
 423     argument::
 424         A Boolean.
 425
 426 METHOD:: timeCursorPosition
 427
 428     The position of the time cursor in frames.
 429
 430     argument::
 431         An Integer.
 432
 433 METHOD:: timeCursorColor
 434
 435     The color of the time cursor.
 436
 437     argument::
 438         A Color.
 439
 440 METHOD:: elasticMode
 441
 442     ???
 443
 444 SUBSECTION:: Actions
 445
 446 METHOD:: action
 447
 448     The object to be evaluated whenever the user interacts with the view.
 449
 450 METHOD:: metaAction
 451
 452     The object to be evaluated on Ctrl + click.
 453
 454
 455 EXAMPLES::
 456
 457 SUBSECTION:: Basic example
 458
 459 code::
 460 (
 461 w = Window.new("soundfile test", Rect(200, 200, 800, 400));
 462 a = SoundFileView.new(w, Rect(20,20, 700, 60));
 463
 464 f = SoundFile.new;
 465 f.openRead("sounds/a11wlk01.wav");
 466 f.inspect;
 467
 468 a.soundfile = f;
 469 a.read(0, f.numFrames);
 470 a.elasticMode = true;
 471
 472 a.timeCursorOn = true;
 473 a.timeCursorColor = Color.red;
 474 a.timeCursorPosition = 2050;
 475 a.drawsWaveForm = true;
 476 a.gridOn = true;
 477 a.gridResolution = 0.2;
 478
 479 w.front;
 480 )
 481 ::
 482
 483 SUBSECTION:: Step by step examples
 484
 485 code::
 486 ( // make a simple SoundFileView
 487 w = Window.new("soundfile test", Rect(10, 700, 750, 100));
 488 w.front;
 489 a = SoundFileView.new(w, Rect(20,20, 700, 60));
 490
 491 f = SoundFile.new;
 492 f.openRead("sounds/a11wlk01.wav");
 493 // f.inspect;
 494
 495 a.soundfile = f;            // set soundfile
 496 a.read(0, f.numFrames);     // read in the entire file.
 497 a.refresh;                  // refresh to display the file.
 498 )
 499
 500 // reading file
 501 a.read(0, f.numFrames / 2).refresh; // read first half
 502 a.read.refresh;                     // read entire file by default
 503 a.read(f.numFrames / 2).refresh;    // read second half
 504 a.read(0, -1).refresh;              // -1 also reads entire file, like buffer.
 505
 506 // block sets visual resolution of waveform, default is 64.
 507 // i.e. the view keeps peak values for each block of e.g. 64 samples
 508 // rather than the entire waveform.
 509 a.read(0, -1, block: 32).refresh;
 510 a.read(0, -1, block: 24).refresh;
 511 a.read(0, -1, block: 16).refresh;
 512
 513 // for longer files, you can use:
 514 a.readWithTask;
 515
 516 // zoom is relative
 517 a.zoom(0.2).refresh;
 518 a.zoom(2).refresh;
 519 a.zoom(2).refresh;
 520 a.zoomToFrac(0.5); // zoom to half file size
 521 a.zoomAllOut;
 522
 523 a.gridOn = true;            // time grid, 1 second by default,
 524 a.gridResolution = 0.2;     // or set resolution in seconds
 525 a.gridColor = Color.cyan;   // color is changeable.
 526 a.gridOffset_(0.1);         // not sure if this is working?
 527
 528 a.timeCursorOn = true;          // a settable cursor
 529 a.timeCursorPosition = 2050;    // position is in frames.
 530 a.timeCursorColor = Color.white;
 531
 532 // toggle drawing on/off
 533 a.drawsWaveForm = false;
 534 a.drawsWaveForm = true;
 535
 536 // these methods should return view properties:
 537 a.gridOn
 538 a.gridResolution
 539 a.gridColor
 540 a.timeCursorOn
 541 a.timeCursorPosition
 542 a.timeCursorColor
 543
 544 // Selections: multiple selections are supported.
 545 // e.g. use selection 0:
 546 a.setSelectionColor(0, Color.red);  // set...( index, value )
 547 a.selectionStart(0);                // at index
 548 a.setSelectionStart(0, 12345);
 549 a.setSelectionSize(0, 12345);
 550
 551 a.setSelectionStart(0, 1234);
 552 a.selectionStart(0);
 553
 554 // now selection 1
 555 a.setSelectionColor(1, Color.white);
 556 a.setSelectionStart(1, 1234).setSelectionSize(1, 1234 * 2);
 557 a.selectionStart(1);
 558 a.setSelectionStart(0, 12345);
 559
 560 // the current selection gets changed when click/dragging in view.
 561 a.currentSelection;     // index of current selection;
 562 a.currentSelection_(1); // switch current selection - try click/drag white now.
 563 a.currentSelection;
 564
 565 a.selections.size;      // 64 selections
 566 a.selections[0];
 567 a.selections[1];
 568 a.selections;
 569
 570 // setSelection (index, selection);
 571 a.setSelection(0, [234, 2345]);
 572 a.selection(1); // returns [start, size].
 573
 574
 575 a.elasticMode = true;   // not sure if this is working yet?
 576
 577 (       // mouseUpAction
 578 a.mouseUpAction = {
 579     ("mouseUp, current selection is now:"
 580         + a.selections[a.currentSelection]).postln;
 581 };
 582 )
 583 // lock selection 0:
 584 a.currentSelection_(0);
 585 a.setEditableSelectionStart(0, false);
 586 a.setEditableSelectionSize(0, false);
 587
 588
 589 // unlock selection 0:
 590 a.setEditableSelectionStart(0, true);
 591 a.setEditableSelectionSize(0, true);
 592
 593 a.selectionStartTime(0);
 594 a.selectionDuration(0);
 595
 596
 597 a.setSelectionStart(0, 12345);
 598 a.setSelectionSize(0, 12345);
 599 a.readSelection.refresh;
 600 a.readSelection(16).refresh;    // in higher resolution
 601 a.read.refresh;                 // go back to entire file.
 602
 603
 604 a.dataNumSamples;   // visual data have this many points
 605 a.data.plot;
 606 a.setData(a.data.reverse);
 607
 608
 609 a.zoom(0.25);       // scrolling is normalized
 610 a.scrollTo(0.5);    //
 611 a.scrollTo(0.6);    //
 612 a.scroll(12);       // scroll is in viewFrames.
 613
 614 a.zoom(4);
 615
 616 w.close;
 617
 618 ::