Interfaccia C per libgSpeech. La libreria libgSpeech espone i simboli dichiarati in questa intestazione.
/*
@brief The Speech object, `G_Speech`, holds Speech resources.
A user of the C-library holds and owns a reference to a `G_Speech` object.
The user is responsible for freeing `G_Speech` with `G_SpeechFree` when done.
`G_Speech` is partially thread safe.
`G_SpeechCreate`, `G_SpeechInit` and `G_SpeechStart` must be called in the
initialization thread.
`G_SpeechPushAudio` and `G_SpeechPollEvents` can both be called from separate
threads. e.g. one audio pushing thread and one event polling thread.
They can also be called in the same thread.
`G_SpeechStop`, `G_SpeechShutdown` and `G_SpeechFree` should be called in the
initialization thread.
*/
typedef struct G_Speech G_Speech;
/*
@brief `G_SpeechEventsOwner` owns the results from `G_Speech`.
When `G_SpeechPollEvents` is called, `G_SpeechEventsOwner` owns the events
that are received.
`G_SpeechPollEvents` populates the `G_SpeechEventsOwner` if events are
available. A user of the C library can retrieve events from the
`G_SpeechEventsOwner` with `G_SpeechGetEvents`.
*/
typedef struct G_SpeechEventsOwner G_SpeechEventsOwner;
/*
@brief `G_SpeechCallContext` can pass or retrieve information from functions.
`G_SpeechCallContext` is used to add/retrieve additional context from functions.
One use-case is retrieving more detailed error message in case of issues
or failures. If a `G_SpeechCallContext` has been passed to a function: an
error message can be retrieved from the `G_SpeechCallContext` with
`G_SpeechGetErrorMessage`. The message is OK if no error occurred.
`G_SpeechCallContext` is **not** thread safe. It can be
reused across function calls but not across threads.
Subsequent calls to the functions with a `G_SpeechCallContext` overrides the
error/message from previous calls.
*/
typedef struct G_SpeechCallContext G_SpeechCallContext;
// @brief Can be passed to indicate that no context is used.
extern G_SpeechCallContext* G_NO_CALL_CONTEXT;
/*
@brief Create a `G_SpeechCallContext`.
The CallContext isn't thread safe. It can and is intended to be re-used between
function calls but shouldn't be shared between threads.
@return (* G_SpeechCallContext) on success, otherwise nullptr.
*/
SPEECH_EXPORT G_SpeechCallContext* G_SpeechCreateCallContext();
/*
@brief Get the error message in a `G_SpeechCallContext`
Ownership:
The `G_SpeechCallContext` retrains ownership of the returned C-string. The
C-string shouldn't be referenced after the context has been passed to a new
call or after it has been cleared.
@param context `G_SpeechCallContext` to get message from.
@return a C-string (NULL-terminated) containing the error message in a
`G_SpeechCallContext`. Returns an empty string if no error is present.
*/
SPEECH_EXPORT const char* G_SpeechGetErrorMessage(G_SpeechCallContext* context);
/*
@brief Clear the error in the `G_SpeechCallContext`.
This deallocates the error message string. Don't reference the string after it
has been deallocated.
@param context `G_SpeechCallContext` to clear error from.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechClearError(G_SpeechCallContext* context);
/*
@brief Free the resources associated with a `G_SpeechCallContext`.
@param context `G_SpeechCallContext` to free.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechFreeCallContext(G_SpeechCallContext* context);
/*
@brief Create a `G_SpeechEventsOwner`.
The `events_owner` holds the events produced by calling `G_SpeechPollEvents`.
@param context Optional `G_SpeechCallContext`.
@return (* G_SpeechEventsOwner) on success, otherwise nullptr.
*/
SPEECH_EXPORT G_SpeechEventsOwner* G_SpeechCreateEventsOwner(
G_SpeechCallContext* context);
/*
@brief `G_SpeechHasEvents` checks if the event owner has any events.
Note: `G_SpeechHasEvents` checks if `G_SpeechEventsOwner` has any events.
`G_Speech` maintains a buffer of all available events. The only way to determine
if it has any events is to call `G_SpeechPollEvents`. When polling, ready events
in `G_Speech` are moved into the `G_SpeechEventsOwner`. After the events are
moved, check if there are any available events.
@param `events_owner` `G_SpeechEventsOwner` to check in.
@param context Optional `G_SpeechCallContext`.
@return True if `events_owner` has events, false if not or on error.
*/
SPEECH_EXPORT bool G_SpeechHasEvents(G_SpeechEventsOwner* events_owner,
G_SpeechCallContext* context);
/*
@brief `G_SpeechGetEvents` adds the events to the output arguments.
Retrieve events from a `G_SpeechEventsOwner` by calling `G_SpeechGetEvents`.
Pass in the `G_SpeechEventsOwner` to retrieve the events and
a `serialized_events` argument and a `num_bytes` argument. `G_SpeechGetEvents`
populates the `serialized_events` argument with the serialized bytes of a proto
and populates the `num_bytes` argument with the number of bytes in the
serialized proto.
Ownership:
`serialized_events`and `num_bytes` is owned by the `G_SpeechEventsOwner` and
not the caller. On the next call to `G_SpeechPollEvents`, this serialized events
resource is released instead of a new resource. After that point, the caller
might not reference the old `serialized_events` or `num_bytes` any longer.
@param `events_owner`, object to retrieve events from.
@param `serialized_events`, points to a pointer pointing to the serialized
events.
@param `num_bytes`, points to an int holding the number of serialized bytes.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechGetEvents(G_SpeechEventsOwner* events_owner,
const char** serialized_events,
int* num_bytes,
G_SpeechCallContext* context);
/*
@brief cleans up all resources associated with the `G_SpeechEventsOwner`.
@param `events_owner`, the `G_SpeechEventsOwner` to free.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechFreeEventsOwner(G_SpeechEventsOwner* events_owner,
G_SpeechCallContext* context);
/*
@brief Create a `G_Speech` instance using a key.
The `G_Speech` instance is owned by the user. The user is responsible for
freeing it with `G_SpeechFree`.
Ownership:
`G_Speech` makes a copy of the key. The caller retains ownership of the string
passed to this function.
@param key is used to initialize `G_Speech`.
@param context Optional `G_SpeechCallContext`.
@return (* G_Speech) on success, otherwise nullptr.
*/
SPEECH_EXPORT G_Speech* G_SpeechCreate(const char* key,
G_SpeechCallContext* context);
/*
@brief Init `G_Speech` with a serialized initialization configuration.
Initialization is a heavy operation. It loads models, resources, and
prepares the recognition pipeline.
Ownership:
`G_Speech` makes a copy of the configuration. The caller retains ownership
of the serialized configuration passed to this function.
@param g_speech is the `G_Speech` object to init.
@param `serialized_init_config` is a serialized proto used init `G_Speech`.
@param `num_bytes`: the number of bytes to read from the
`serialized_init_config`.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechInit(G_Speech* g_speech,
const char* serialized_init_config,
int num_bytes, G_SpeechCallContext* context);
/*
@brief `G_SpeechIsPrepared`: true if the Speech pipeline is initialized and not
shutdown.
This returns true if Speech has been initialized and not yet shutdown.
If true, this means that Speech is one of the following:
- In the process of initializing.
- Initialized.
- In the process of shutting down.
@param g_speech is the `G_Speech` object to check if it is prepared.
@param context Optional `G_SpeechCallContext`.
@return True if prepared, false if not or on error.
*/
SPEECH_EXPORT bool G_SpeechIsPrepared(G_Speech* g_speech,
G_SpeechCallContext* context);
/*
@brief Start `G_Speech` with a serialized start configuration.
`G_SpeechStart` starts the recognition pipeline and allows passing of dynamic
configurations should as Speech adaptation.
Ownership:
`G_Speech` makes a copy of the configuration. The caller retains ownership
of the serialized configuration passed to this function.
@param g_speech is the `G_Speech` object to check if it is prepared.
@param `serialized_start_config` is a serialized proto used start `G_Speech`.
@param `num_bytes`: the number of bytes to read from the
`serialized_start_config`.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechStart(G_Speech* g_speech,
const char* serialized_start_config,
int num_bytes, G_SpeechCallContext* context);
/*
@brief `G_SpeechIsRunning` checks if the Speech pipeline is active.
`G_SpeechIsRunning` returns true if Speech has been started and not yet stopped.
If true, this means that Speech is one of the following:
- In the process of starting.
- Started.
- In the process of stopping.
@param g_speech is the `G_Speech` object to check if it is running.
@param context Optional `G_SpeechCallContext`.
@return True if running, false if not or on error.
*/
SPEECH_EXPORT bool G_SpeechIsRunning(G_Speech* g_speech,
G_SpeechCallContext* context);
/*
@brief `G_SpeechMarkEndOfAudio` indicates that there won't be any more audio
pushed using `G_SpeechPushAudio`.
Invoke `G_SpeechMarkEndOfAudio` to indicate that we have finished streaming
audio from the current source. After calling `G_SpeechMarkEndOfAudio`, don't
push the audio to `G_SpeechPushAudio` without restarting it using `G_SpeechStop`
and `G_SpeechStart`. Pushing audio results in an error.
This is useful when transcribing from a finite source of audio, such as an audio
file. By marking a stream as done, `G_Speech` can indicate that it is done
processing through the END_OF_AUDIO AudioEvent.
*/
bool G_SpeechMarkEndOfAudio(G_Speech* g_speech, G_SpeechCallContext* context);
/*
@brief `G_SpeechPushAudio` pushes audio into the Speech pipeline.
The audio has to be of the same type as the one specified in the initialization
configuration.
`G_Speech` expects audio to be streamed in approximately **REAL-TIME**.
Streaming faster or slower than real time can yield unexpected results.
Ownership:
`G_Speech` makes a copy of the audio, the caller retains ownership
of the audio passed to this function.
@param g_speech is the `G_Speech` object to push audio into.
@param audio to push into `G_Speech`.
@param `num_bytes` of the audio to push into `G_Speech`.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechPushAudio(G_Speech* g_speech, const char* audio,
int num_bytes,
G_SpeechCallContext* context);
enum G_SpeechPollType { NON_BLOCKING = 1, BLOCKING_TIMEOUT = 2, BLOCKING = 3 };
/*
@brief `G_SpeechPollEvents` polls the recognition pipeline for ready events.
If BLOCKING_TIMEOUT is used, it blocks for `timeout_ms` milliseconds. After
polling, ready events are added to the `events_owner`.
**If the `events_owner` has events, they are released.**
@param g_speech is the `G_Speech` object to poll from.
@param `events_owner` retrieves all available events.
@param polling_type indicates how to poll for the events.
@param timeout_ms indicates how long to wait in case of a timeout polling.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error. True doesn't indicate the presence
of events.
*/
SPEECH_EXPORT bool G_SpeechPollEvents(G_Speech* g_speech,
G_SpeechEventsOwner* events_owner,
enum G_SpeechPollType polling_type,
int timeout_ms,
G_SpeechCallContext* context);
/*
@brief Stop the recognition pipeline.
The pipeline can be started again with a new start configuration.
@param g_speech is the `G_Speech` object to stop.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechStop(G_Speech* g_speech,
G_SpeechCallContext* context);
/*
@brief Shutdown `G_Speech`.
Speech can be initialized again with a new initialization configuration.
Shutting down frees most resources, it unloads models from memory.
This shouldn't be called before stopping.
@param g_speech is the `G_Speech` object to shutdown.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechShutdown(G_Speech* g_speech,
G_SpeechCallContext* context);
/*
@brief `G_SpeechFree` cleans up the `G_Speech` object.
This shouldn't be called before shutting down.
@param g_speech is the `G_Speech` object to free.
@param context Optional `G_SpeechCallContext`.
@return True if successful, false on error.
*/
SPEECH_EXPORT bool G_SpeechFree(G_Speech* g_speech,
G_SpeechCallContext* context);