Add more Waveform analysis examples and class documentation

kevinstadler commented 5 years ago

With the addition of the Waveform analysis class (see #21 and #22) it would be nice to add another example or two with the same simply waveform visualisation but of different inputs, for example an "OscillatorWaveform" example that's parallel to the "OscillatorSpectrum' one, and also an "AudioInputWaveform" one parallel to the existing "AudioInput" one.

In order for the new class' documentation to show up on the website, the corresponding .xml files also still need to be added to https://github.com/processing/processing-docs/tree/master/content/api_en/LIB_sound

mhamilt commented 4 years ago

I'm not to familiar with the architecture of processing-docs, but is this just a case of pulling in a file Waveform.xml with the content

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root>

<name>Waveform</name>

<category>Sound</category>

<subcategory>Analyzer</subcategory>

<usage>Application</usage>

<example>
<image></image>
<code><![CDATA[
import processing.sound.*;

SoundFile sample;
Waveform waveform;

int samples = 100;

public void setup()
{
  size(640, 360);
  background(255);

  sample = new SoundFile(this, "beat.aiff");
  sample.loop();

  waveform = new Waveform(this, samples);
  waveform.input(sample);
}

public void draw()
{
  background(0);
  stroke(255);
  strokeWeight(2);
  noFill();

  waveform.analyze();

  beginShape();
  for(int i = 0; i < samples; i++)
  {
    vertex(
      map(i, 0, samples, 0, width),
      map(waveform.data[i], -1, 1, 0, height)
    );
  }
  endShape();
}
]]></code>
</example>

<description><![CDATA[
  This is a Waveform analyzer. It returns the waveform of the of an audio stream the moment it is queried with the analyze() method.
]]></description>

<syntax>
</syntax>

<parameters>

</parameters>

<method>
<mname>input()</mname>
<mdescription>Define the audio input for the analyzer</mdescription>
</method>

<method>
<mname>analyze()</mname>
<mdescription>Gets the content of the current audiobuffer from the input source, writes it
 into this Waveform's `data` array, and returns it.</mdescription>
</method>

<method>
<mname>stop()</mname>
<mdescription>Stop the analyzer</mdescription>
</method>

<method>
<mname>data</mname>
<mdescription>`float[]` of sample amplitudes between `-1` and `1`</mdescription>
</method>

<constructor>
Waveform(<c>parent</c>)
</constructor>

<cparameter>
<clabel>parent</clabel>
<cdescription>PApplet: typically use "this"</cdescription>
</cparameter>

<returns></returns>

<related>
</related>

<availability>1.0</availability>

<type>Object</type>

<partof>Library</partof>

</root>

kevinstadler commented 4 years ago

That looks great, thanks! Yeah this file should go into processing-docs, and then also just the Java code bit in the examples folder of this repository. I'm working on the next release of the library, so I'll make sure they are included!

mhamilt commented 4 years ago

great!

Seems weird for me to have put .data in <method> tags though.

<method>
<mname>data</mname>
<mdescription>`float[]` of sample amplitudes between `-1` and `1`</mdescription>
</method>

I couldn't find another instance of a class that has documentation of a member variable / class property, not in the format of the sound library xml files that is.

dhowe commented 4 years ago

Any progress on this? I still don't see don't see any entry for Waveform in the docs or the javadocs...

processing / processing-sound

Add more Waveform analysis examples and class documentation #26