sound.html

perl教程

                channels
                support</pre>
</dd>
<dd>
<pre>
    AUX........ technology
                support</pre>
</dd>
<dd>
<pre>
    MIXER...... destinations
                support</pre>
</dd>
<dd>
<p>The meaning of the fields, where not
obvious, can be evinced from the
Microsoft SDK documentation (too long
to report here, maybe one day... :-).</p>
</dd>
<dd>
<p>Example:</p>
</dd>
<dd>
<pre>
    <span class="variable">%info</span> <span class="operator">=</span> <span class="variable">Win32::Sound::DeviceInfo</span><span class="operator">(</span><span class="string">'WAVE_MAPPER'</span><span class="operator">);</span>
    <span class="keyword">print</span> <span class="string">"$info{name} version $info{driver_version}\n"</span><span class="operator">;</span>
</pre>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="the_waveout_package">THE WaveOut PACKAGE</a></h1>
<p>Win32::Sound also provides a different, more
powerful approach to wave audio data with its
<a href="#item_waveout"><code>WaveOut</code></a> package. It has methods to load and
then play WAV files, with the additional feature
of specifying the start and end range, so you
can play only a portion of an audio file.</p>
<p>Furthermore, it is possible to load arbitrary
binary data to the soundcard to let it play and
save them back into WAV files; in a few words,
you can do some sound synthesis work.</p>
<p>
</p>
<h2><a name="functions">FUNCTIONS</a></h2>
<dl>
<dt><strong><a name="item_waveout">new Win32::Sound::WaveOut(FILENAME)</a></strong>

<dt><strong>new Win32::Sound::WaveOut(SAMPLERATE, BITS, CHANNELS)</strong>

<dt><strong>new Win32::Sound::WaveOut()</strong>

<dd>
<p>This function creates a <a href="#item_waveout"><code>WaveOut</code></a> object; the
first form opens the specified wave file (see
also <a href="#item_open"><code>Open()</code></a> ), so you can directly <a href="#item_play"><code>Play()</code></a> it.</p>
</dd>
<dd>
<p>The second (and third) form opens the
wave output device with the format given
(or if none given, defaults to 44.1kHz,
16 bits, stereo); to produce something
audible you can either <a href="#item_open"><code>Open()</code></a> a wave file
or <a href="#item_load"><code>Load()</code></a> binary data to the soundcard
and then <a href="#item_write"><code>Write()</code></a> it.</p>
</dd>
</li>
<dt><strong><a name="item_close"><code>Close()</code></a></strong>

<dd>
<p>Closes the wave file currently opened.</p>
</dd>
</li>
<dt><strong><a name="item_closedevice"><code>CloseDevice()</code></a></strong>

<dd>
<p>Closes the wave output device; you can change
format and reopen it with <a href="#item_opendevice"><code>OpenDevice()</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_geterrortext"><code>GetErrorText(ERROR)</code></a></strong>

<dd>
<p>Returns the error text associated with
the specified ERROR number; note it only
works for wave-output-specific errors.</p>
</dd>
</li>
<dt><strong><a name="item_load"><code>Load(DATA)</code></a></strong>

<dd>
<p>Loads the DATA buffer in the soundcard.
The format of the data buffer depends
on the format used; for example, with
8 bit mono each sample is one character,
while with 16 bit stereo each sample is
four characters long (two 16 bit values
for left and right channels). The sample
rate defines how much samples are in one
second of sound. For example, to fit one
second at 44.1kHz 16 bit stereo your buffer
must contain 176400 bytes (44100 * 4).</p>
</dd>
</li>
<dt><strong><a name="item_open"><code>Open(FILE)</code></a></strong>

<dd>
<p>Opens the specified wave FILE.</p>
</dd>
</li>
<dt><strong><a name="item_opendevice"><code>OpenDevice()</code></a></strong>

<dd>
<p>Opens the wave output device with the
current sound format (not needed unless
you used <a href="#item_closedevice"><code>CloseDevice()</code></a>).</p>
</dd>
</li>
<dt><strong><a name="item_pause"><code>Pause()</code></a></strong>

<dd>
<p>Pauses the sound currently playing;
use <a href="#item_restart"><code>Restart()</code></a> to continue playing.</p>
</dd>
</li>
<dt><strong>Play( [FROM, TO] )</strong>

<dd>
<p>Plays the opened wave file. You can optionally
specify a FROM - TO range, where FROM and TO
are expressed in samples (or use FROM=0 for the
first sample and TO=-1 for the last sample).
Playback happens always asynchronously, eg. in
the background.</p>
</dd>
</li>
<dt><strong><a name="item_position"><code>Position()</code></a></strong>

<dd>
<p>Returns the sample number currently playing;
note that the play position is not zeroed
when the sound ends, so you have to call a
<a href="#item_reset"><code>Reset()</code></a> between plays to receive the
correct position in the current sound.</p>
</dd>
</li>
<dt><strong><a name="item_reset"><code>Reset()</code></a></strong>

<dd>
<p>Stops playing and resets the play position
(see <a href="#item_position"><code>Position()</code></a>).</p>
</dd>
</li>
<dt><strong><a name="item_restart"><code>Restart()</code></a></strong>

<dd>
<p>Continues playing the sound paused by <a href="#item_pause"><code>Pause()</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_save">Save(FILE, [DATA])</a></strong>

<dd>
<p>Writes the DATA buffer (if not given, uses the
buffer currently loaded in the soundcard)
to the specified wave FILE.</p>
</dd>
</li>
<dt><strong><a name="item_status"><code>Status()</code></a></strong>

<dd>
<p>Returns 0 if the soundcard is currently playing,
1 if it's free, or <a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> on errors.</p>
</dd>
</li>
<dt><strong><a name="item_unload"><code>Unload()</code></a></strong>

<dd>
<p>Frees the soundcard from the loaded data.</p>
</dd>
</li>
<dt><strong>Volume( [LEFT, RIGHT] )</strong>

<dd>
<p>Gets or sets the volume for the wave output device.
It works the same way as Win32::Sound::Volume.</p>
</dd>
</li>
<dt><strong><a name="item_write"><code>Write()</code></a></strong>

<dd>
<p>Plays the data currently loaded in the soundcard;
playback happens always asynchronously, eg. in
the background.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="the_sound_format">THE SOUND FORMAT</a></h2>
<p>The sound format is stored in three properties of
the <a href="#item_waveout"><code>WaveOut</code></a> object: <code>samplerate</code>, <code>bits</code> and
<a href="#item_channels"><code>channels</code></a>.
If you need to change them without creating a
new object, you should close before and reopen
afterwards the device.</p>
<pre>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">CloseDevice</span><span class="operator">();</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">samplerate</span><span class="operator">}</span> <span class="operator">=</span> <span class="number">44100</span><span class="operator">;</span> <span class="comment"># 44.1kHz</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">bits</span><span class="operator">}</span>       <span class="operator">=</span> <span class="number">8</span><span class="operator">;</span>     <span class="comment"># 8 bit</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">channels</span><span class="operator">}</span>   <span class="operator">=</span> <span class="number">1</span><span class="operator">;</span>     <span class="comment"># mono</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">OpenDevice</span><span class="operator">();</span>
</pre>
<p>You can also use the properties to query the
sound format currently used.</p>
<p>
</p>
<h2><a name="example">EXAMPLE</a></h2>
<p>This small example produces a 1 second sinusoidal
wave at 440Hz and saves it in <em>sinus.wav</em>:</p>
<pre>
    <span class="keyword">use</span> <span class="variable">Win32::Sound</span><span class="operator">;</span>
</pre>
<pre>
    <span class="comment"># Create the object</span>
    <span class="variable">$WAV</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">Win32::Sound::WaveOut</span><span class="operator">(</span><span class="number">44100</span><span class="operator">,</span> <span class="number">8</span><span class="operator">,</span> <span class="number">2</span><span class="operator">);</span>
</pre>
<pre>
    <span class="variable">$data</span> <span class="operator">=</span> <span class="string">""</span><span class="operator">;</span>
    <span class="variable">$counter</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
    <span class="variable">$increment</span> <span class="operator">=</span> <span class="number">440</span><span class="operator">/</span><span class="number">44100</span><span class="operator">;</span>
</pre>
<pre>
    <span class="comment"># Generate 44100 samples ( = 1 second)</span>
    <span class="keyword">for</span> <span class="variable">$i</span> <span class="operator">(</span><span class="number">1</span><span class="operator">..</span><span class="number">44100</span><span class="operator">)</span> <span class="operator">{</span>
</pre>
<pre>
        <span class="comment"># Calculate the pitch</span>
        <span class="comment"># (range 0..255 for 8 bits)</span>
        <span class="variable">$v</span> <span class="operator">=</span> <span class="keyword">sin</span><span class="operator">(</span><span class="variable">$counter</span><span class="operator">/</span><span class="number">2</span><span class="operator">*</span><span class="number">3.14</span><span class="operator">)</span> <span class="operator">*</span> <span class="number">128</span> <span class="operator">+</span> <span class="number">128</span><span class="operator">;</span>
</pre>
<pre>
        <span class="comment"># "pack" it twice for left and right</span>
        <span class="variable">$data</span> <span class="operator">.=</span> <span class="keyword">pack</span><span class="operator">(</span><span class="string">"cc"</span><span class="operator">,</span> <span class="variable">$v</span><span class="operator">,</span> <span class="variable">$v</span><span class="operator">);</span>
</pre>
<pre>
        <span class="variable">$counter</span> <span class="operator">+=</span> <span class="variable">$increment</span><span class="operator">;</span>
            <span class="operator">}</span>
</pre>
<pre>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">Load</span><span class="operator">(</span><span class="variable">$data</span><span class="operator">);</span>       <span class="comment"># get it</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">Write</span><span class="operator">();</span>           <span class="comment"># hear it</span>
    <span class="number">1</span> <span class="keyword">until</span> <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">Status</span><span class="operator">();</span>  <span class="comment"># wait for completion</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">Save</span><span class="operator">(</span><span class="string">"sinus.wav"</span><span class="operator">);</span> <span class="comment"># write to disk</span>
    <span class="variable">$WAV</span><span class="operator">-&gt;</span><span class="variable">Unload</span><span class="operator">();</span>          <span class="comment"># drop it</span>
</pre>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>Win32::Sound version 0.46, 25 Sep 1999.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Aldo Calpini, <code>[e-mail]</code></p>
<p>Parts of the code provided and/or suggested by Dave Roth.</p>

</body>

</html>