README.md

PvSpeaker

Made in Vancouver, Canada by Picovoice

PvSpeaker is an easy-to-use, cross-platform audio player designed for real-time speech audio processing. It allows developers to send raw PCM frames to an audio device's output stream.

Table of Contents

• PvSpeaker
  • Table of Contents
  • Source Code
  • Demos
    • Python
    • .NET
    • Node.js
    • C
  • SDKs
    • Python
    • .NET
    • Node.js

Source Code

If you are interested in building PvSpeaker from source or integrating it into an existing C project, the PvSpeaker source code is located under the /project directory.

Demos

If using SSH, clone the repository with:

git clone --recurse-submodules [email protected]:Picovoice/pvspeaker.git

If using HTTPS, clone the repository with:

git clone --recurse-submodules https://github.com/Picovoice/pvspeaker.git

Python Demo

Install the demo package:

pip3 install pvspeakerdemo

To show the available audio devices run:

pv_speaker_demo --show_audio_devices

With a working speaker connected to your device run the following in the terminal:

pv_speaker_demo --input_wav_path {INPUT_WAV_PATH}

Replace {INPUT_WAV_PATH} with the path to the PCM WAV file you wish to play.

For more information about the Python demos go to demo/python.

.NET Demo

From demo/dotnet/PvSpeakerDemo run the following in the terminal to build the demo:

dotnet build

Make sure there is a working speaker connected to your device. From demo/dotnet/PvSpeakerDemo run the following in the terminal:

dotnet run -- --input_wav_path ${INPUT_WAV_FILE}

For more information about the .NET demo, go to demo/dotnet.

Node.js Demo

Install the demo package:

yarn global add @picovoice/pvspeaker-node-demo

To show the available audio devices run:

pvspeaker-node-demo --show_audio_devices

With a working speaker connected to your device run the following in the terminal:

pvspeaker-node-demo --input_wav_path ${INPUT_WAV_PATH}

Replace {INPUT_WAV_PATH} with the path to the wav file you wish to play.

For more information about Node.js demo, go to demo/nodejs.

C Demo

Run the following commands to build the demo app:

cd demo/c
cmake -S . -B build -DPV_SPEAKER_PLATFORM={PV_SPEAKER_PLATFORM}
cmake --build build

The {PV_SPEAKER_PLATFORM} variable will set the compilation flags for the given platform. Exclude this variable to get a list of possible values.

Get a list of available audio player devices:

./pv_speaker_demo --show_audio_devices

Play from a single-channel PCM WAV file with a given audio device index:

./pv_speaker_demo -i test.wav -d 2

Hit Ctrl+C if you wish to stop playing audio before it completes. If no audio device index (-d) is provided, the demo will use the system's default audio player device.

For more information about the C demo, go to demo/c.

SDKs

Python

To start playing audio, initialize an instance and run start():

from pvspeaker import PvSpeaker

speaker = PvSpeaker(
    sample_rate=22050,
    bits_per_sample=16,
    device_index=0)

speaker.start()

Write PCM data to the speaker:

def get_next_audio_frame():
    pass

speaker.write(get_next_audio_frame())

Note: the write() method only writes as much PCM data as the internal circular buffer can currently fit, and returns the length of the PCM data that was successfully written.

When all frames have been written, run flush() to wait for all buffered PCM data (i.e. previously buffered via write()) to be played:

speaker.flush()

Note: calling flush() with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.

def get_remaining_audio_frames():
    pass

speaker.flush(get_remaining_audio_frames())

To stop the audio output device, run stop():

speaker.stop()

Note that in order to stop the audio before it finishes playing, stop must be run on a separate thread from flush.

Once you are done (i.e. no longer need PvSpeaker to write and/or play PCM), free the resources acquired by PvSpeaker by calling delete. Be sure to first call stop if the audio is still playing. Otherwise, if the audio has already finished playing, you do not have to call stop before delete:

speaker.delete()

For more information about the PvSpeaker Python SDK, go to binding/python.

.NET

Install the .NET SDK using NuGet or the dotnet CLI:

dotnet add package PvSpeaker

Usage

Initialize and start PvSpeaker:

using Pv;

var speaker = new PvSpeaker(
    sampleRate: 22050,
    bitsPerSample: 16);

speaker.Start();

Write PCM data to the speaker:

public static byte[] GetNextAudioFrame() { }

int writtenLength = speaker.Write(GetNextAudioFrame());

Note: the Write() method only writes as much PCM data as the internal circular buffer can currently fit, and returns the number of samples that were successfully written.

When all frames have been written, run Flush() to wait for all buffered PCM data (i.e. previously buffered via Write()) to be played:

int flushedLength = speaker.Flush();

Note: calling Flush() with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.

public static byte[] GetRemainingAudioFrames() { }

int flushedLength = speaker.Flush(GetRemainingAudioFrames());

To stop the audio output device, run Stop():

speaker.Stop();

Once you are done, free the resources acquired by PvSpeaker. You do not have to call Stop() before Dispose():

speaker.Dispose();

For more information about the PvSpeaker .NET SDK, go to binding/dotnet.

Node.js

Install Node.js binding:

yarn add @picovoice/pvspeaker-node

To start playing audio, initialize the instance and run start():

const { PvSpeaker } = require("@picovoice/pvspeaker-node");

const sampleRate = 22050;
const bitsPerSample = 16;
const deviceIndex = 0;
const speaker = new PvSpeaker(sampleRate, bitsPerSample, { deviceIndex });

speaker.start()

Write PCM data to the speaker:

function getNextAudioFrame(): ArrayBuffer {
    //
}

speaker.write(getNextAudioFrame())

Note: the write() method only writes as much PCM data as the internal circular buffer can currently fit, and returns the length of the PCM data that was successfully written.

When all frames have been written, run flush() to wait for all buffered PCM data (i.e. previously buffered via write()) to be played:

speaker.flush()

Note: calling flush() with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.

function getRemainingAudioFrames(): ArrayBuffer {
    //
}

speaker.flush(getRemainingAudioFrames())

To stop the audio output device, run stop():

speaker.stop();

Once you are done (i.e. no longer need PvSpeaker to write and/or play PCM), free the resources acquired by PvSpeaker by calling release. You do not have to call stop before release:

speaker.release();

For more information about the PvSpeaker Node.js SDK, go to binding/nodejs.