From 67df47c0db268877c9699a657566bdf9430bad48 Mon Sep 17 00:00:00 2001 From: jqueguiner Date: Mon, 30 Dec 2024 21:25:21 +0100 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20(speaker-reidentification):=20a?= =?UTF-8?q?dd=20new=20documentation=20for=20speaker=20reidentification=20f?= =?UTF-8?q?eature=20to=20provide=20users=20with=20guidance=20on=20usage=20?= =?UTF-8?q?and=20configuration=20=F0=9F=93=9D=20(api-parameters):=20update?= =?UTF-8?q?=20API=20parameters=20documentation=20to=20include=20speaker=20?= =?UTF-8?q?reidentification=20settings=20for=20better=20clarity=20?= =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(mint.json):=20refactor=20mint.json=20to?= =?UTF-8?q?=20include=20the=20new=20speaker=20reidentification=20page=20in?= =?UTF-8?q?=20the=20documentation=20structure?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pages/speaker-reidentification.mdx | 100 ++++++++++++++++++ docs/api-parameters.md | 3 + mint.json | 3 +- 3 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 chapters/audio-intelligence/pages/speaker-reidentification.mdx create mode 100644 docs/api-parameters.md diff --git a/chapters/audio-intelligence/pages/speaker-reidentification.mdx b/chapters/audio-intelligence/pages/speaker-reidentification.mdx new file mode 100644 index 0000000..f9d814f --- /dev/null +++ b/chapters/audio-intelligence/pages/speaker-reidentification.mdx @@ -0,0 +1,100 @@ +--- +title: "Speaker Reidentification (Alpha)" +description: "Learn how to use speaker reidentification to track and identify speakers across multiple audio files" +--- + +# Speaker Reidentification (Alpha) + + + +This feature is on **Alpha** state. + +We're looking for feedbacks to improve this feature, [share yours here](https://gladiaio.typeform.com/feedback?typeform-source=app.gladia.io). + + + +Speaker reidentification allows you to track and identify speakers across multiple audio files by maintaining a database of speaker voice signatures. This feature is particularly useful for organizations that need to analyze conversations from multiple recordings while maintaining speaker consistency. + +## Overview + +When speaker reidentification is enabled, the system will: +1. Extract voice signatures from speakers in the audio +2. Compare these signatures with previously stored speakers +3. Assign consistent identifiers to matching speakers +4. Optionally save new speaker signatures for future identification + +## Configuration + +To enable speaker reidentification, set `speaker_reidentification` to `true` in your API request and provide the configuration through `speaker_reidentification_config`: + +```json +{ + "speaker_reidentification": true, + "speaker_reidentification_config": { + "filters": { + "customer_id": "123", + "company": "gladia", + "department": "tech" + }, + "save_new_speakers": true, + "save_new_speaker_similarity_threshold": 0.95, + "boost_uuids": [] + } +} +``` + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `speaker_reidentification` | boolean | Enable/disable speaker reidentification | +| `speaker_reidentification_config` | object | Configuration object for speaker reidentification | + +### Speaker Reidentification Config Options + +| Option | Type | Description | +|--------|------|-------------| +| `filters` | object | Filters to scope the speaker database search | +| `filters.customer_id` | string | Example of parameter called "customer_id" for scoping speaker search to a specific customer | +| `filters.company` | string | Example of parameter called "company" or Company name for scoping speaker search to a specific company that might be customer of your organization | +| `filters.department` | string | Example of parameter called "department" or Department name for further scoping to a specific department within a company that might be customer of your organization | +| `filters.whatever` | string | Example of parameter for further whatever scoping you need | +| `save_new_speakers` | boolean | Whether to save new speaker signatures to the database | +| `save_new_speaker_similarity_threshold` | float | Minimum similarity threshold (0-1) for saving new speakers (if we don't find a match withing this threshold) | +| `boost_uuids` | array | List of speaker UUIDs to prioritize in matching | + +## Example Usage +We recommand activating the diarization and speaker reidentification features at the same time if you plan to identify mutliple speakers within the same audio. +Here's a complete example of using speaker reidentification with the API: + +```json +{ + "sentences": false, + "diarization": true, + "speaker_reidentification": true, + "speaker_reidentification_config": { + "filters": { + "customer_id": "123", + "company": "gladia", + "department": "tech" + }, + "save_new_speakers": true, + "save_new_speaker_similarity_threshold": 0.95, + "boost_uuids": [] + }, + "audio_url": "https://api.gladia.io/audio/sample.wav" +} +``` + +## Best Practices + +1. Always enable `diarization` when using speaker reidentification unless you have a specific reason not to (for instance speaker voiceprint registration) +2. Use appropriate filters to narrow down the speaker database search scope +3. Set a high `save_new_speaker_similarity_threshold` (e.g., 0.95) to ensure quality matches +4. Use `boost_uuids` when you want to prioritize matching with specific known speakers + +## Limitations + +- Speaker reidentification requires good quality audio for accurate matching +- Performance may vary based on audio quality and background noise +- The feature works best with clear speech and minimal overlapping voices diff --git a/docs/api-parameters.md b/docs/api-parameters.md new file mode 100644 index 0000000..62818b0 --- /dev/null +++ b/docs/api-parameters.md @@ -0,0 +1,3 @@ +## Speaker Reidentification + +You can enable speaker reidentification by setting: \ No newline at end of file diff --git a/mint.json b/mint.json index 290a7ef..09e8c1f 100644 --- a/mint.json +++ b/mint.json @@ -189,7 +189,8 @@ "chapters/audio-intelligence/pages/sentiment analysis", "chapters/audio-intelligence/pages/moderation", "chapters/audio-intelligence/pages/chapterization", - "chapters/audio-intelligence/pages/audio to llm" + "chapters/audio-intelligence/pages/audio to llm", + "chapters/audio-intelligence/speaker-reidentification" ] }, { From bf18ddefb0e65a9b349207407898f7f4f09c6ff5 Mon Sep 17 00:00:00 2001 From: jqueguiner Date: Mon, 30 Dec 2024 21:25:43 +0100 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20(api-parameters.md):=20remov?= =?UTF-8?q?e=20outdated=20documentation=20on=20speaker=20reidentification?= =?UTF-8?q?=20to=20maintain=20accuracy=20and=20clarity=20in=20API=20docume?= =?UTF-8?q?ntation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-parameters.md | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 docs/api-parameters.md diff --git a/docs/api-parameters.md b/docs/api-parameters.md deleted file mode 100644 index 62818b0..0000000 --- a/docs/api-parameters.md +++ /dev/null @@ -1,3 +0,0 @@ -## Speaker Reidentification - -You can enable speaker reidentification by setting: \ No newline at end of file From 1939749a917e0dec904eb6b4309d71a72340dcb9 Mon Sep 17 00:00:00 2001 From: jlqueguiner Date: Thu, 9 Jan 2025 12:07:37 +0100 Subject: [PATCH 3/4] chore(speaker-reidentification.mdx): update example code and output for speaker reidentification The example code and output for speaker reidentification have been updated to reflect the changes in the API. The "filters" field in the "speaker_reidentification_config" object has been removed, as it is no longer necessary. Additionally, the "audio_url" field has been updated to use a different audio file for testing. The example output now includes two scenarios: one for a known speaker and one for an unknown speaker who has been newly enrolled. The output includes information such as the speaker's score, creation and update timestamps, last accessed timestamp, whether the speaker is new or not, and the speaker's UUID. These changes improve the clarity and accuracy of the example code and output for speaker reidentification. --- .../pages/speaker-reidentification.mdx | 57 +++++++++++++++++-- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/chapters/audio-intelligence/pages/speaker-reidentification.mdx b/chapters/audio-intelligence/pages/speaker-reidentification.mdx index f9d814f..60847af 100644 --- a/chapters/audio-intelligence/pages/speaker-reidentification.mdx +++ b/chapters/audio-intelligence/pages/speaker-reidentification.mdx @@ -73,16 +73,61 @@ Here's a complete example of using speaker reidentification with the API: "diarization": true, "speaker_reidentification": true, "speaker_reidentification_config": { - "filters": { - "customer_id": "123", - "company": "gladia", - "department": "tech" - }, + "filters": {}, "save_new_speakers": true, "save_new_speaker_similarity_threshold": 0.95, "boost_uuids": [] }, - "audio_url": "https://api.gladia.io/audio/sample.wav" + "audio_url": "https://files.gladia.io/example/audio-transcription/split_infinity.wav" +} +``` + +### Example Output for a Known Speaker +```json +"speaker_reidentification": { + "success": true, + "is_empty": false, + "results": { + "0": [ + { + "score": 1.0000001, + "created_at_timestamp": 1736419219.108255, + "updated_at_timestamp": null, + "created_at_iso": "2025-01-09T10:40:19.108256", + "updated_at_iso": null, + "last_accessed_timestamp": 1736419347.55111, + "last_accessed_iso": "2025-01-09T10:42:27.551116", + "is_new_speaker": false, + "uuid": "fc04030f-5ad4-46f6-b9a0-8c238675165f", + "filters": {} + } + // More matched speakers... + ] + } +} +``` + +### Example Output for an Unknown Speaker newly enrolled +```json +"speaker_reidentification": { + "success": true, + "is_empty": false, + "results": { + "6": [ + { + "score": 1.0000001, + "created_at_timestamp": 1736419302.801952, + "updated_at_timestamp": null, + "created_at_iso": "2025-01-09T10:41:42.801953", + "updated_at_iso": null, + "last_accessed_timestamp": 1736419500.189427, + "last_accessed_iso": "2025-01-09T10:45:00.189431", + "is_new_speaker": true, # true if the speaker is not found in the database but has been enrolled + "uuid": "c24c1436-6139-46f9-bcd8-4d633889661a", + "filters": {} + } + ] + } } ``` From ddbfc923cfe43412b6b4bf34f057df80e6a4de2b Mon Sep 17 00:00:00 2001 From: jlqueguiner Date: Thu, 9 Jan 2025 21:58:56 +0100 Subject: [PATCH 4/4] feat(enterprise-api.mdx): add Gladia Enterprise Portal API documentation This commit adds the Gladia Enterprise Portal API documentation. The documentation provides comprehensive functionality for managing subaccounts, API keys, usage monitoring, and data retention settings. It covers all available endpoints and their usage. The documentation includes the following sections: - Introduction: Provides an overview of the API and its functionality. - Base URL: Specifies the base URL that should be used for all API paths. - Authentication: Explains how authentication details should be provided. - API Endpoints: Describes all available API endpoints and their usage. - Error Handling: Explains how errors are handled and provides an example of the error response format. - Best Practices: Provides recommendations for using the API effectively. - Support: Provides contact information for additional support or questions about the API. This documentation will serve as a reference for developers using the Gladia Enterprise Portal API. --- chapters/enterprise/enterprise-api.mdx | 178 +++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 chapters/enterprise/enterprise-api.mdx diff --git a/chapters/enterprise/enterprise-api.mdx b/chapters/enterprise/enterprise-api.mdx new file mode 100644 index 0000000..3013a3b --- /dev/null +++ b/chapters/enterprise/enterprise-api.mdx @@ -0,0 +1,178 @@ +# Gladia Enterprise Portal API Documentation + +## Introduction + +The Gladia Enterprise Portal API provides comprehensive functionality for managing subaccounts, API keys, usage monitoring, and data retention settings. This documentation covers all available endpoints and their usage. + +## Base URL + +All API paths described below should be appended to your base API URL. + +## Authentication + +Authentication details should be provided by your system administrator. + +## API Endpoints + +### Subaccount Management + +#### Create Subaccount +`POST /subaccount` + +Creates a new subaccount in the system. + +**Request Body:** +```json +{ + "email": "string", + "account_name": "string", + "usage_notification_threshold": "number", + "notification_emails": "string", + "monthly_limit_consumption_in_hours": "number" +} +``` + +All fields are required. + +### Notification Settings + +#### Set Notification Emails +`POST /set-notification-emails` + +Configure email notifications for a user account. + +**Query Parameters:** +- `email` (required): The email of the user +- `emails` (required): Comma-separated list of email addresses to receive notifications + +#### Set Monthly Limit Consumption +`POST /set-monthly-limit-consumption-in-hours` + +Set the monthly usage limit for a user account. + +**Query Parameters:** +- `email` (required): The email of the user +- `limit` (required): Monthly limit in hours (numeric value) + +#### Set Usage Notification Threshold +`POST /set-usage-notification-threshold` + +Configure the threshold at which usage notifications are triggered. + +**Query Parameters:** +- `email` (required): The email of the user +- `threshold` (required): Threshold value (numeric) + +### Usage Monitoring + +#### Get Account Consumption +`GET /consumption` + +Retrieve consumption data for a specific account. + +**Query Parameters:** +- `email` (required): The email of the user to get consumption data for + +#### Get All Accounts Consumption +`GET /consumptions` + +Retrieve consumption data for all subaccounts under the master account. + +#### Export Consumption Data +`GET /export-consumption-csv` + +Export consumption data for a specific account in CSV format. + +**Query Parameters:** +- `email` (required): The email of the user + +#### Export All Consumptions +`GET /export-consumptions-csv` + +Export consumption data for all accounts in CSV format, with dates as rows and users as columns. + +### API Key Management + +#### Get API Keys +`GET /account-api-keys` + +Retrieve all API keys for an account. + +**Query Parameters:** +- `email` (required): The email of the user + +#### Create API Key +`POST /account-api-keys` + +Create a new API key for an account. + +**Query Parameters:** +- `email` (required): The email of the user +- `name` (optional): Name for the API key + +#### Update API Key Name +`PATCH /account-api-keys` + +Update the name of an existing API key. + +**Query Parameters:** +- `email` (required): The email of the user +- `api_key` (required): The API key to update +- `new_name` (required): New name for the API key + +#### Delete API Key +`DELETE /account-api-keys` + +Mark an API key as deleted. + +**Query Parameters:** +- `email` (required): The email of the user +- `api_key` (required): The API key to delete + +#### Reactivate API Key +`PATCH /reactivate-account-api-key` + +Reactivate a previously deleted API key. + +**Query Parameters:** +- `email` (required): The email of the user +- `api_key` (required): The API key to reactivate + +### Data Retention + +#### Update Data Retention Period +`PATCH /user-data-retention` + +Set the data retention period for a user account. + +**Query Parameters:** +- `email` (required): The email of the user +- `data_retention_in_days` (required): Number of days to retain data + +## Error Handling + +The API uses standard HTTP response codes to indicate success or failure of requests. In case of validation errors, the response will include detailed information about the error in the following format: + +```json +{ + "detail": [ + { + "loc": ["field_name"], + "msg": "error message", + "type": "error type" + } + ] +} +``` + +## Best Practices + +1. Always handle API responses appropriately and check for error conditions +2. Store API keys securely and never expose them in client-side code +3. Implement proper retry logic for failed requests +4. Monitor consumption regularly to avoid hitting usage limits +5. Keep notification email lists up to date + +## Support + +For additional support or questions about the API, please contact your account manager.