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