Skip to content

Commit

Permalink
Merge pull request #17 from fixie-ai/sdk-examples
Browse files Browse the repository at this point in the history 
add language examples for SDK
  • Loading branch information
@benlower
benlower authored Sep 12, 2024
2 parents 1e593e2 + 5054fe0 commit c11418a
Show file tree
Hide file tree
Showing 4 changed files with 122 additions and 299 deletions.
1 change: 1 addition & 0 deletions docs/src/assets/logos/github-mark.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
81 changes: 55 additions & 26 deletions docs/src/components/SDKCards.astro
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
---
import { CardGrid, Card } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import flutterLogo from '../assets/logos/flutter.svg';
import jsLogo from '../assets/logos/js.svg';
import kotlinLogo from '../assets/logos/kotlin.svg';
import pythonLogo from '../assets/logos/python.svg';
import { CardGrid, Card, Icon } from "@astrojs/starlight/components";
import { Image } from "astro:assets";
import flutterLogo from "../assets/logos/flutter.svg";
import jsLogo from "../assets/logos/js.svg";
import kotlinLogo from "../assets/logos/kotlin.svg";
import pythonLogo from "../assets/logos/python.svg";
import ghLogo from "../assets/logos/github-mark.svg";
const wordForNum: { [key: number]: string } = {
3: 'three', 4: 'four', 5: 'five', 6: 'six', 7: 'seven',
8: 'eight', 9: 'nine', 10: 'ten'
3: "three",
4: "four",
5: "five",
6: "six",
7: "seven",
8: "eight",
9: "nine",
10: "ten",
};
function numToWord(num: number): string {
Expand All @@ -23,7 +30,8 @@ const sdks = [
installCommand: "flutter add ultravox_client",
introLinkText: "Get it on ",
linkText: "pub.dev",
linkUrl: "https://pub.dev/packages/ultravox_client"
linkUrl: "https://pub.dev/packages/ultravox_client",
repo: "https://github.com/fixie-ai/ultravox-client-sdk-flutter",
},
{
title: "JavaScript",
Expand All @@ -32,15 +40,18 @@ const sdks = [
installCommand: "npm install ultravox-client",
introLinkText: "Available in the ",
linkText: "npm registry",
linkUrl: "https://www.npmjs.com/package/ultravox-client"
linkUrl: "https://www.npmjs.com/package/ultravox-client",
repo: "https://github.com/fixie-ai/ultravox-client-sdk-js",
},
{
title: "Kotlin",
logo: kotlinLogo,
logoAlt: "Kotlin logo",
introLinkText: "Find it on ",
linkText: "Maven Central",
linkUrl: "https://central.sonatype.com/artifact/ai.fixie/ultravox-client-sdk"
linkUrl:
"https://central.sonatype.com/artifact/ai.fixie/ultravox-client-sdk",
repo: "https://github.com/fixie-ai/ultravox-client-sdk-android",
},
{
title: "Python",
Expand All @@ -49,27 +60,45 @@ const sdks = [
installCommand: "pip install ultravox-client",
introLinkText: "More info on ",
linkText: "PyPi",
linkUrl: "https://pypi.org/project/ultravox-client/"
}
linkUrl: "https://pypi.org/project/ultravox-client/",
repo: "https://github.com/fixie-ai/ultravox-client-sdk-python",
},
];
---

<div class="sdk-cards">
There are currently {numToWord(sdks.length)} implementations of the SDK available:
<br />
<CardGrid>
{sdks.map((lang) => (
<Card title={lang.title}>
<Image src={lang.logo} width={24} alt={lang.logoAlt} />
{lang.installCommand && (
<>
<code>{lang.installCommand}</code>
<br />
</>
)}
{lang.introLinkText} <a href={lang.linkUrl}>{lang.linkText}</a>
</Card>
))}
{
sdks.map((lang) => (
<Card title={lang.title}>
<div class="flex flex-row items-end h-6 mb-4">
<Image
src={lang.logo}
height={24}
alt={lang.logoAlt}
class="mr-2"
/>
{lang.installCommand && (
<div>
<code>{lang.installCommand}</code>
</div>
)}
</div>

<div class="flex flex-row items-center w-full justify-between h-10">
<div>
{lang.introLinkText} <a href={lang.linkUrl}>{lang.linkText}</a>
</div>
<div>
<a href={lang.repo} class="">
<Image src={ghLogo} height={18} alt="Github logo" />
</a>
</div>
</div>
</Card>
))
}
</CardGrid>
</div>
88 changes: 66 additions & 22 deletions docs/src/content/docs/sdk.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,57 @@ sidebar:
import { Tabs, TabItem } from '@astrojs/starlight/components';
import SDKCards from '../../components/SDKCards.astro';

The Ultravox [REST API](../api/auth/) is used to create calls but you must use one of the Ultravox client SDKs to join and end calls. This page uses examples in JavaScript. The concepts are the same across all the [different SDK implementations](#sdk-implementations).
The Ultravox [REST API](../api/auth/) is used to create calls but you must use one of the Ultravox client SDKs to join and end calls. This page primarily uses examples in JavaScript. The concepts are the same across all the [different SDK implementations](#sdk-implementations).

## Ultravox Session
The core of the SDK is the `UltravoxSession`. The session is used to join and leave calls.

```javascript
import { UltravoxSession } from 'ultravox-client';
<Tabs syncKey="example-language">
<TabItem label="JavaScript">
```js
import { UltravoxSession } from 'ultravox-client';

const session = new UltravoxSession();
const state = await session.joinCall('wss://your-call-join-url');
const session = new UltravoxSession();
const state = await session.joinCall('wss://your-call-join-url');

session.leaveCall();
```
session.leaveCall();
```
</TabItem>

<TabItem label="Flutter">
```dart
import 'package:ultravox_client/ultravox_client.dart';
UltravoxSession session = UltravoxSession.create();
UltravoxSessionState state = await _session.joinCall('wss://your-call-join-url');
await session.leaveCall();
```
</TabItem>

<TabItem label="Kotlin">
```kotlin
import ai.ultravox.UltravoxSession

val session = UltravoxSession()
val state = session.joinCall("wss://your-call-join-url")

session.leaveCall()
```
</TabItem>

<TabItem label="Python">
```python
import asyncio
import ultravox_client as uv

session = uv.UltravoxSession()
state = await session.join_call("wss://your-call-join-url")

await session.leave_call()
```
</TabItem>
</Tabs>

## Session State
When a call is joined, an `UltravoxSessionState` is returned. This object returns the current status, can be used to get text transcripts of the call, and surfaces debug messages that are helpful when building your application.
Expand All @@ -37,21 +75,27 @@ The session status is based on the `UltravoxSessionStatus` enum and can be one o
| thinking | The model is processing/thinking. |
| speaking | The model is speaking. |

The status can be retrieved by adding an event listener to the state:

```javascript
import { UltravoxSession } from 'ultravox-client';

const session = new UltravoxSession();
const state = await session.joinCall('wss://your-call-join-url');

// Listen for status changing events
state.addEventListener('ultravoxSessionStatusChanged', (event) => {
console.log('Session status changed: ', event.state);
});

session.leaveCall();
```
#### Status Events
The status can be retrieved by adding an event listener to the state. Building on what we did above:

<Tabs syncKey="example-language">
<TabItem label="JavaScript">
```js
// Listen for status changing events
state.addEventListener('ultravoxSessionStatusChanged', (event) => {
console.log('Session status changed: ', event.state);
});
```
</TabItem>

<TabItem label="Flutter">
```dart
state.addListener(() {
print('Status is now ${state.status}');
})
```
</TabItem>
</Tabs>

### Transcripts
Sometimes you may want to augment the audio with text transcripts (e.g. if you want to show the end user the model's output in real-time). Transcripts can be retrieved by adding an event listener to state:
Expand Down
Loading

0 comments on commit c11418a

Please sign in to comment.