Skip to content

Commit

Permalink
readme updates (#718)
Browse files Browse the repository at this point in the history
  • Loading branch information
@laves
laves authored Oct 27, 2023
1 parent ad3faeb commit 4f5212d
Show file tree
Hide file tree
Showing 5 changed files with 131 additions and 158 deletions.
91 changes: 44 additions & 47 deletions sdk/flutter/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,14 @@ import 'package:picovoice/picovoice_error.dart';
final String accessKey = "{ACCESS_KEY}"; // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
_picovoiceManager = PicovoiceManager.create(
accessKey,
"/path/to/keyword/file.ppn",
_wakeWordCallback,
"/path/to/context/file.rhn",
_inferenceCallback);
try {
_picovoiceManager = await PicovoiceManager.create(
accessKey,
"/path/to/keyword/file.ppn",
_wakeWordCallback,
"/path/to/context/file.rhn",
_inferenceCallback);
} on PicovoiceException catch(ex) { }
```

The `wakeWordCallback` and `inferenceCallback` parameters are functions that you want to execute when a wake word is detected and when an inference is made.
Expand All @@ -95,12 +97,12 @@ The `inferenceCallback` callback function takes a parameter of `RhinoInference`
- slots - **null** if `isUnderstood` is not true, otherwise the dictionary of slot keys and values that were inferred

```dart
void _wakeWordCallback(){
void _wakeWordCallback() {
// wake word detected
}
void _inferenceCallback(RhinoInference inference) {
if(inference.isUnderstood!) {
if (inference.isUnderstood!) {
String intent = inference.intent!;
Map<String, String> slots = inference.slots!;
// add code to take action based on inferred intent and slot values
Expand All @@ -123,22 +125,22 @@ Picovoice accepts the following optional parameters:
```dart
final String accessKey = "{ACCESS_KEY}"; // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
void createPicovoiceManager() {
double porcupineSensitivity = 0.7;
double rhinoSensitivity = 0.6;
_picovoiceManager = PicovoiceManager.create(
accessKey,
"/path/to/keyword/file.ppn",
wakeWordCallback,
"/path/to/context/file.rhn",
inferenceCallback,
porcupineSensitivity: porcupineSensitivity,
rhinoSensitivity: rhinoSensitivity,
porcupineModelPath: "/path/to/porcupine/model.pv",
rhinoModelPath: "/path/to/rhino/model.pv",
endpointDurationSec: 1.5,
requireEndpoint: false,
errorCallback: _errorCallback);
void createPicovoiceManager() async {
try {
_picovoiceManager = await PicovoiceManager.create(
accessKey,
"/path/to/keyword/file.ppn",
wakeWordCallback,
"/path/to/context/file.rhn",
inferenceCallback,
porcupineSensitivity: 0.7,
rhinoSensitivity: 0.6,
porcupineModelPath: "/path/to/porcupine/model.pv",
rhinoModelPath: "/path/to/rhino/model.pv",
endpointDurationSec: 1.5,
requireEndpoint: false,
errorCallback: _errorCallback);
} on PicovoiceException catch(ex) { }
}
void _errorCallback(PicovoiceException error) {
Expand All @@ -151,15 +153,21 @@ Once you have instantiated a PicovoiceManager, you can start audio capture and p
```dart
try {
await _picovoiceManager.start();
} on PicovoiceException catch(ex) {
// deal with Picovoice init error
}
} on PicovoiceException catch(ex) { }
```

And then stop it by calling:

```dart
await _picovoiceManager.stop();
try {
await _picovoiceManager.stop();
} on PicovoiceException catch(ex) { }
```

Finally, once you no longer need the `PicovoiceManager`, be sure to explicitly release the resources allocated to it:

```dart
await _picovoiceManager.delete();
```

PicovoiceManager uses our
Expand All @@ -180,27 +188,20 @@ import 'package:picovoice/picovoice_error.dart';
final String accessKey = "{ACCESS_KEY}"; // AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
void createPicovoice() async {
double porcupineSensitivity = 0.7;
double rhinoSensitivity = 0.6;
double endpointDurationSec = 1.5;
bool requireEndpoint = false;
try{
try {
_picovoice = await Picovoice.create(
accessKey,
"/path/to/keyword/file.ppn",
wakeWordCallback,
"/path/to/context/file.rhn",
inferenceCallback,
porcupineSensitivity,
rhinoSensitivity,
porcupineSensitivity: 0.7,
rhinoSensitivity: 0.6,
"/path/to/porcupine/model.pv",
"/path/to/rhino/model.pv",
endpointDurationSec
requireEndpoint);
} on PicovoiceException catch (err) {
// handle picovoice init error
}
endpointDurationSec: 1.5,
requireEndpoint: false);
} on PicovoiceException catch (ex) { }
}
void wakeWordCallback() {
Expand All @@ -226,9 +227,7 @@ List<int> buffer = getAudioFrame();
try {
_picovoice.process(buffer);
} on PicovoiceException catch (error) {
// handle error
}
} on PicovoiceException catch (ex) { }
```

For process to work correctly, the audio data must be in the audio format required by Picovoice.
Expand Down Expand Up @@ -264,9 +263,7 @@ try {
wakeWordCallback,
contextAsset,
inferenceCallback);
} on PicovoiceException catch (err) {
// handle picovoice init error
}
} on PicovoiceException catch (ex) { }
```

Alternatively, if the custom models are deployed to the device with a different method, the absolute paths to the files on device can be used.
Expand Down
56 changes: 30 additions & 26 deletions sdk/ios/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,35 +53,39 @@ import Picovoice

let accessKey = "${ACCESS_KEY}" // obtained from Picovoice Console (https://console.picovoice.ai/)

let manager = PicovoiceManager(
accessKey: accessKey,
keywordPath: "/path/to/keyword.ppn",
onWakeWordDetection: {
// logic to execute upon detection of wake word
},
contextPath: "/path/to/context.rhn",
onInference: { inference in
// logic to execute upon completion of intent inference
})
do {
let picovoiceManager = try PicovoiceManager(
accessKey: accessKey,
keywordPath: "/path/to/keyword.ppn",
onWakeWordDetection: {
// logic to execute upon detection of wake word
},
contextPath: "/path/to/context.rhn",
onInference: { inference in
// logic to execute upon completion of intent inference
})
} catch { }
```

The constructor also allows you to override the default model files and/or the sensitivities of Porcupine and Rhino:

```swift
let accessKey = "${ACCESS_KEY}" // obtained from Picovoice Console (https://console.picovoice.ai/)

let manager = PicovoiceManager(
accessKey: accessKey,
keywordPath: "/path/to/keyword.ppn",
porcupineSensitivity: 0.4,
porcupineModelPath: "/path/to/porcupine/model.pv",
onWakeWordDetection: wakeWordCallback,
contextPath: "/path/to/context.rhn",
rhinoSensitivity: 0.7,
rhinoModelPath: "/path/to/rhino/model.pv",
onInference: inferenceCallback,
endpointDurationSec: 1.5,
requireEndpoint: false)
do {
let picovoiceManager = try PicovoiceManager(
accessKey: accessKey,
keywordPath: "/path/to/keyword.ppn",
porcupineSensitivity: 0.4,
porcupineModelPath: "/path/to/porcupine/model.pv",
onWakeWordDetection: wakeWordCallback,
contextPath: "/path/to/context.rhn",
rhinoSensitivity: 0.7,
rhinoModelPath: "/path/to/rhino/model.pv",
onInference: inferenceCallback,
endpointDurationSec: 1.5,
requireEndpoint: false)
} catch { }
```

Sensitivity is the parameter that enables trading miss rate for the false alarm rate. It is a floating-point number within [0, 1]. A higher sensitivity reduces the miss rate at the cost of increased false alarm rate.
Expand All @@ -92,14 +96,14 @@ Once you have instantiated a PicovoiceManager, you can start audio capture and v

```swift
do {
try manager.start()
try picovoiceManager.start()
} catch { }
```

Stop the manager with:
```swift
do {
manager.stop();
try picovoiceManager.stop()
} catch { }
```

Expand Down Expand Up @@ -143,12 +147,12 @@ Once initialized, `picovoice` can be used to process incoming audio. The underly
```swift
func getNextAudioFrame() -> [Int16] {
// .. get audioFrame
return audioFrame;
return audioFrame
}

while (true) {
do {
try picovoice.process(getNextAudioFrame());
try picovoice.process(getNextAudioFrame())
} catch { }
}
```
Expand Down
20 changes: 9 additions & 11 deletions sdk/java/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,8 @@ PicovoiceInferenceCallback inferenceCallback = inference -> {
// ..
};

try{
Picovoice handle = new Picovoice.Builder()
try {
Picovoice picovoice = new Picovoice.Builder()
.setAccessKey(accessKey)
.setKeywordPath(keywordPath)
.setWakeWordCallback(wakeWordCallback)
Expand All @@ -93,34 +93,32 @@ try{
} catch (PicovoiceException e) { }
```

`handle` is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at
`picovoice` is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at
`keywordPath`. Upon detection of wake word it starts inferring user's intent from the follow-on voice command within
the context defined by the file located at `contextPath`. `keywordPath` is the absolute path to
[Porcupine wake word engine](https://github.com/Picovoice/porcupine) keyword file (with `.ppn` suffix).
`contextPath` is the absolute path to [Rhino Speech-to-Intent engine](https://github.com/Picovoice/rhino) context file
(with `.rhn` suffix). `wakeWordCallback` is invoked upon the detection of wake phrase and `inferenceCallback` is
invoked upon completion of follow-on voice command inference.

When instantiated, valid sample rate can be obtained via `handle.getSampleRate()`. Expected number of audio samples per
frame is `handle.getFrameLength()`. The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio.
When instantiated, valid sample rate can be obtained via `.getSampleRate()`. Expected number of audio samples per
frame is `.getFrameLength()`. The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio.

```java
short[] getNextAudioFrame()
{
short[] getNextAudioFrame() {
// .. get audioFrame
return audioFrame;
}

while(true)
{
handle.process(getNextAudioFrame());
while(true) {
picovoice.process(getNextAudioFrame());
}
```

Once you're done with Picovoice, ensure you release its resources explicitly:

```java
handle.delete();
picovoice.delete();
```

## Non-English Models
Expand Down
14 changes: 7 additions & 7 deletions sdk/python/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Create a new instance of Picovoice runtime engine
from picovoice import Picovoice

access_key = "${ACCESS_KEY}" # AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)

keyword_path = ...

def wake_word_callback():
Expand All @@ -52,37 +52,37 @@ def inference_callback(inference):
# (3) `slots`
pass

handle = Picovoice(
picovoice = Picovoice(
access_key=access_key,
keyword_path=keyword_path,
wake_word_callback=wake_word_callback,
context_path=context_path,
inference_callback=inference_callback)
```

`handle` is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at
`picovoice` is an instance of Picovoice runtime engine that detects utterances of wake phrase defined in the file located at
`keyword_path`. Upon detection of wake word it starts inferring user's intent from the follow-on voice command within
the context defined by the file located at `context_path`. `keyword_path` is the absolute path to
[Porcupine wake word engine](https://github.com/Picovoice/porcupine) keyword file (with `.ppn` suffix).
`context_path` is the absolute path to [Rhino Speech-to-Intent engine](https://github.com/Picovoice/rhino) context file
(with `.rhn` suffix). `wake_word_callback` is invoked upon the detection of wake phrase and `inference_callback` is
invoked upon completion of follow-on voice command inference.

When instantiated, valid sample rate can be obtained via `handle.sample_rate`. Expected number of audio samples per
frame is `handle.frame_length`. The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio.
When instantiated, valid sample rate can be obtained via `.sample_rate`. Expected number of audio samples per
frame is `.frame_length`. The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio.

```python
def get_next_audio_frame():
pass

while True:
handle.process(get_next_audio_frame())
picovoice.process(get_next_audio_frame())
```

When done resources have to be released explicitly

```python
handle.delete()
picovoice.delete()
```

## Non-English Models
Expand Down
Loading

0 comments on commit 4f5212d

Please sign in to comment.