├── .env.example ├── .eslintrc.json ├── .github ├── assets │ ├── app-icon.png │ ├── frontend-screenshot.jpeg │ └── template-graphic.svg └── workflows │ ├── build-and-test.yaml │ └── sync-to-production.yaml ├── .gitignore ├── .prettierignore ├── .prettierrc ├── LICENSE ├── README.md ├── TEMPLATE.md ├── app ├── api │ └── connection-details │ │ └── route.ts ├── favicon.ico ├── globals.css ├── layout.tsx └── page.tsx ├── components ├── CloseIcon.tsx ├── NoAgentNotification.tsx └── TranscriptionView.tsx ├── hooks ├── useCombinedTranscriptions.ts └── useLocalMicTrack.ts ├── next.config.mjs ├── package.json ├── pnpm-lock.yaml ├── postcss.config.mjs ├── renovate.json ├── tailwind.config.ts ├── taskfile.yaml └── tsconfig.json /.env.example: -------------------------------------------------------------------------------- 1 | # Enviroment variables needed to connect to the LiveKit server. 2 | LIVEKIT_API_KEY= 3 | LIVEKIT_API_SECRET= 4 | LIVEKIT_URL=wss://.livekit.cloud 5 | -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": ["next/core-web-vitals", "next/typescript", "prettier"] 3 | } 4 | -------------------------------------------------------------------------------- /.github/assets/app-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/livekit-examples/voice-assistant-frontend/a0292ef1d150617dac78c6dfe903aeedcd7b9ce6/.github/assets/app-icon.png -------------------------------------------------------------------------------- /.github/assets/frontend-screenshot.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/livekit-examples/voice-assistant-frontend/a0292ef1d150617dac78c6dfe903aeedcd7b9ce6/.github/assets/frontend-screenshot.jpeg -------------------------------------------------------------------------------- /.github/assets/template-graphic.svg: -------------------------------------------------------------------------------- 1 | 73 | -------------------------------------------------------------------------------- /.github/workflows/build-and-test.yaml: -------------------------------------------------------------------------------- 1 | name: Lint and Build 2 | permissions: 3 | contents: read 4 | pull-requests: read 5 | on: 6 | push: 7 | branches: [main] 8 | pull_request: 9 | branches: [main] 10 | 11 | jobs: 12 | test: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@v4 16 | - uses: pnpm/action-setup@v4 17 | - name: Use Node.js 22 18 | uses: actions/setup-node@v4 19 | with: 20 | node-version: 22 21 | cache: "pnpm" 22 | 23 | - name: Install dependencies 24 | run: pnpm install 25 | 26 | - name: ESLint 27 | run: pnpm lint 28 | 29 | - name: Prettier 30 | run: pnpm format:check 31 | 32 | - name: Ensure build succeeds 33 | run: pnpm build 34 | -------------------------------------------------------------------------------- /.github/workflows/sync-to-production.yaml: -------------------------------------------------------------------------------- 1 | # .github/workflows/sync-main-to-sandbox-production.yml 2 | 3 | name: Sync main to sandbox-production 4 | 5 | on: 6 | push: 7 | branches: 8 | - main 9 | 10 | permissions: 11 | contents: write 12 | pull-requests: write 13 | 14 | jobs: 15 | sync: 16 | runs-on: ubuntu-latest 17 | 18 | steps: 19 | - name: Checkout code 20 | uses: actions/checkout@v3 21 | with: 22 | fetch-depth: 0 # Fetch all history so we can force push 23 | 24 | - name: Set up Git 25 | run: | 26 | git config --global user.name 'github-actions[bot]' 27 | git config --global user.email 'github-actions[bot]@livekit.io' 28 | 29 | - name: Sync to sandbox-production 30 | env: 31 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 32 | run: | 33 | git checkout sandbox-production || git checkout -b sandbox-production 34 | git merge --strategy-option theirs main 35 | git push origin sandbox-production 36 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 2 | 3 | # dependencies 4 | /node_modules 5 | /.pnp 6 | .pnp.js 7 | .yarn/install-state.gz 8 | 9 | # testing 10 | /coverage 11 | 12 | # next.js 13 | /.next/ 14 | /out/ 15 | 16 | # production 17 | /build 18 | 19 | # misc 20 | .DS_Store 21 | *.pem 22 | 23 | # debug 24 | npm-debug.log* 25 | yarn-debug.log* 26 | yarn-error.log* 27 | 28 | # local env files 29 | .env*.local 30 | 31 | # vercel 32 | .vercel 33 | 34 | # typescript 35 | *.tsbuildinfo 36 | next-env.d.ts 37 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | .github/ 2 | dist/ 3 | docs/ 4 | node_modules/ 5 | .next/ 6 | yarn.lock 7 | pnpm-lock.yaml 8 | 9 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "singleQuote": false, 3 | "trailingComma": "es5", 4 | "semi": true, 5 | "tabWidth": 2, 6 | "printWidth": 100, 7 | "importOrder": ["", "^[./]"], 8 | "importOrderSeparation": false, 9 | "importOrderSortSpecifiers": true, 10 | "importOrderParserPlugins": ["typescript", "jsx"], 11 | "plugins": ["@trivago/prettier-plugin-sort-imports"] 12 | } 13 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 LiveKit, Inc. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | # Web Voice Assistant 4 | 5 | This is a starter template for [LiveKit Agents](https://docs.livekit.io/agents) that provides a simple voice interface using the [LiveKit JavaScript SDK](https://github.com/livekit/client-sdk-js). It supports [voice](https://docs.livekit.io/agents/start/voice-ai), [transcriptions](https://docs.livekit.io/agents/build/text/), and [virtual avatars](https://docs.livekit.io/agents/integrations/avatar). 6 | 7 | This template is built with Next.js and is free for you to use or modify as you see fit. 8 | 9 | ![App screenshot](/.github/assets/frontend-screenshot.jpeg) 10 | 11 | ## Getting started 12 | 13 | > [!TIP] 14 | > If you'd like to try this application without modification, you can deploy an instance in just a few clicks with [LiveKit Cloud Sandbox](https://cloud.livekit.io/projects/p_/sandbox/templates/voice-assistant-frontend). 15 | 16 | Run the following command to automatically clone this template. 17 | 18 | ```bash 19 | lk app create --template voice-assistant-frontend 20 | ``` 21 | 22 | Then run the app with: 23 | 24 | ```bash 25 | pnpm install 26 | pnpm dev 27 | ``` 28 | 29 | And open http://localhost:3000 in your browser. 30 | 31 | You'll also need an agent to speak with. Try our [Voice AI Quickstart](https://docs.livekit.io/start/voice-ai) for the easiest way to get started. 32 | 33 | > [!NOTE] 34 | > If you need to modify the LiveKit project credentials used, you can edit `.env.local` (copy from `.env.example` if you don't have one) to suit your needs. 35 | 36 | ## Contributing 37 | 38 | This template is open source and we welcome contributions! Please open a PR or issue through GitHub, and don't forget to join us in the [LiveKit Community Slack](https://livekit.io/join-slack)! 39 | -------------------------------------------------------------------------------- /TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | A Next.js frontend for a simple AI voice assistant using LiveKit's official [JavaScript SDK](https://github.com/livekit/client-sdk-js) and [React Components](https://github.com/livekit/components-js). The application implements its own token server, and supports [voice](https://docs.livekit.io/agents/start/voice-ai/), [transcription](https://docs.livekit.io/agents/build/text/), and [virtual avatars](https://docs.livekit.io/agents/integrations/avatar/). 4 | 5 | ## Sandbox 6 | 7 | When deployed in a sandbox, LiveKit will host an instance of this application for you, providing a unique, shareable URL through which you can access it. Any agents running with the same LiveKit project credentials will join, meaning that you can rapidly iterate on your agent prototypes, and share the results instantly with friends and colleagues. To begin testing your agent, deploy this app in sandbox then set up an agent on your local machine using the [Voice AI Quickstart](https://docs.livekit.io/start/voice-ai): 8 | 9 | ## Installation 10 | 11 | To run this application locally, clone the repo or use the [LiveKit CLI](https://docs.livekit.io/home/cli/cli-setup/): 12 | 13 | ```console 14 | lk app create --template voice-assistant-frontend 15 | ``` 16 | 17 | For more information on prototyping using LiveKit Sandbox, see the [documentation](https://docs.livekit.io/home/cloud/sandbox/). 18 | -------------------------------------------------------------------------------- /app/api/connection-details/route.ts: -------------------------------------------------------------------------------- 1 | import { AccessToken, AccessTokenOptions, VideoGrant } from "livekit-server-sdk"; 2 | import { NextResponse } from "next/server"; 3 | 4 | // NOTE: you are expected to define the following environment variables in `.env.local`: 5 | const API_KEY = process.env.LIVEKIT_API_KEY; 6 | const API_SECRET = process.env.LIVEKIT_API_SECRET; 7 | const LIVEKIT_URL = process.env.LIVEKIT_URL; 8 | 9 | // don't cache the results 10 | export const revalidate = 0; 11 | 12 | export type ConnectionDetails = { 13 | serverUrl: string; 14 | roomName: string; 15 | participantName: string; 16 | participantToken: string; 17 | }; 18 | 19 | export async function GET() { 20 | try { 21 | if (LIVEKIT_URL === undefined) { 22 | throw new Error("LIVEKIT_URL is not defined"); 23 | } 24 | if (API_KEY === undefined) { 25 | throw new Error("LIVEKIT_API_KEY is not defined"); 26 | } 27 | if (API_SECRET === undefined) { 28 | throw new Error("LIVEKIT_API_SECRET is not defined"); 29 | } 30 | 31 | // Generate participant token 32 | const participantIdentity = `voice_assistant_user_${Math.floor(Math.random() * 10_000)}`; 33 | const roomName = `voice_assistant_room_${Math.floor(Math.random() * 10_000)}`; 34 | const participantToken = await createParticipantToken( 35 | { identity: participantIdentity }, 36 | roomName 37 | ); 38 | 39 | // Return connection details 40 | const data: ConnectionDetails = { 41 | serverUrl: LIVEKIT_URL, 42 | roomName, 43 | participantToken: participantToken, 44 | participantName: participantIdentity, 45 | }; 46 | const headers = new Headers({ 47 | "Cache-Control": "no-store", 48 | }); 49 | return NextResponse.json(data, { headers }); 50 | } catch (error) { 51 | if (error instanceof Error) { 52 | console.error(error); 53 | return new NextResponse(error.message, { status: 500 }); 54 | } 55 | } 56 | } 57 | 58 | function createParticipantToken(userInfo: AccessTokenOptions, roomName: string) { 59 | const at = new AccessToken(API_KEY, API_SECRET, { 60 | ...userInfo, 61 | ttl: "15m", 62 | }); 63 | const grant: VideoGrant = { 64 | room: roomName, 65 | roomJoin: true, 66 | canPublish: true, 67 | canPublishData: true, 68 | canSubscribe: true, 69 | }; 70 | at.addGrant(grant); 71 | return at.toJwt(); 72 | } 73 | -------------------------------------------------------------------------------- /app/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/livekit-examples/voice-assistant-frontend/a0292ef1d150617dac78c6dfe903aeedcd7b9ce6/app/favicon.ico -------------------------------------------------------------------------------- /app/globals.css: -------------------------------------------------------------------------------- 1 | @tailwind base; 2 | @tailwind components; 3 | @tailwind utilities; 4 | 5 | :root { 6 | --lk-va-bar-width: 72px; 7 | --lk-control-bar-height: unset; 8 | } 9 | 10 | .agent-visualizer > .lk-audio-bar { 11 | width: 72px; 12 | } 13 | 14 | .lk-agent-control-bar { 15 | @apply border-t-0 p-0 h-min mr-4; 16 | } 17 | 18 | .lk-disconnect-button { 19 | @apply h-[36px] hover:bg-[#6b221a] hover:text-[white] bg-[#31100c] border-[#6b221a]; 20 | } 21 | -------------------------------------------------------------------------------- /app/layout.tsx: -------------------------------------------------------------------------------- 1 | import "@livekit/components-styles"; 2 | import { Metadata } from "next"; 3 | import { Public_Sans } from "next/font/google"; 4 | import "./globals.css"; 5 | 6 | const publicSans400 = Public_Sans({ 7 | weight: "400", 8 | subsets: ["latin"], 9 | }); 10 | 11 | export const metadata: Metadata = { 12 | title: "Voice Assistant", 13 | }; 14 | 15 | export default function RootLayout({ 16 | children, 17 | }: Readonly<{ 18 | children: React.ReactNode; 19 | }>) { 20 | return ( 21 | 22 | {children} 23 | 24 | ); 25 | } 26 | -------------------------------------------------------------------------------- /app/page.tsx: -------------------------------------------------------------------------------- 1 | "use client"; 2 | 3 | import { CloseIcon } from "@/components/CloseIcon"; 4 | import { NoAgentNotification } from "@/components/NoAgentNotification"; 5 | import TranscriptionView from "@/components/TranscriptionView"; 6 | import { 7 | BarVisualizer, 8 | DisconnectButton, 9 | RoomAudioRenderer, 10 | RoomContext, 11 | VideoTrack, 12 | VoiceAssistantControlBar, 13 | useVoiceAssistant, 14 | } from "@livekit/components-react"; 15 | import { AnimatePresence, motion } from "framer-motion"; 16 | import { Room, RoomEvent } from "livekit-client"; 17 | import { useCallback, useEffect, useState } from "react"; 18 | import type { ConnectionDetails } from "./api/connection-details/route"; 19 | 20 | export default function Page() { 21 | const [room] = useState(new Room()); 22 | 23 | const onConnectButtonClicked = useCallback(async () => { 24 | // Generate room connection details, including: 25 | // - A random Room name 26 | // - A random Participant name 27 | // - An Access Token to permit the participant to join the room 28 | // - The URL of the LiveKit server to connect to 29 | // 30 | // In real-world application, you would likely allow the user to specify their 31 | // own participant name, and possibly to choose from existing rooms to join. 32 | 33 | const url = new URL( 34 | process.env.NEXT_PUBLIC_CONN_DETAILS_ENDPOINT ?? "/api/connection-details", 35 | window.location.origin 36 | ); 37 | const response = await fetch(url.toString()); 38 | const connectionDetailsData: ConnectionDetails = await response.json(); 39 | 40 | await room.connect(connectionDetailsData.serverUrl, connectionDetailsData.participantToken); 41 | await room.localParticipant.setMicrophoneEnabled(true); 42 | }, [room]); 43 | 44 | useEffect(() => { 45 | room.on(RoomEvent.MediaDevicesError, onDeviceFailure); 46 | 47 | return () => { 48 | room.off(RoomEvent.MediaDevicesError, onDeviceFailure); 49 | }; 50 | }, [room]); 51 | 52 | return ( 53 |

54 | 55 |

56 | 57 |

58 | 59 |

60 | ); 61 | } 62 | 63 | function SimpleVoiceAssistant(props: { onConnectButtonClicked: () => void }) { 64 | const { state: agentState } = useVoiceAssistant(); 65 | 66 | return ( 67 | <> 68 | 69 | {agentState === "disconnected" ? ( 70 | 78 | props.onConnectButtonClicked()} 84 | > 85 | Start a conversation 86 | 87 | 88 | ) : ( 89 | 97 | 98 |

99 | 100 |

101 |

102 | 103 |

104 | 105 | 106 | 107 | )} 108 | 109 | 110 | ); 111 | } 112 | 113 | function AgentVisualizer() { 114 | const { state: agentState, videoTrack, audioTrack } = useVoiceAssistant(); 115 | 116 | if (videoTrack) { 117 | return ( 118 |

119 | 120 |

121 | ); 122 | } 123 | return ( 124 |

125 | 132 |

133 | ); 134 | } 135 | 136 | function ControlBar(props: { onConnectButtonClicked: () => void }) { 137 | const { state: agentState } = useVoiceAssistant(); 138 | 139 | return ( 140 |

141 | 142 | {agentState === "disconnected" && ( 143 | props.onConnectButtonClicked()} 150 | > 151 | Start a conversation 152 | 153 | )} 154 | 155 | 156 | {agentState !== "disconnected" && agentState !== "connecting" && ( 157 | 164 | 165 | 166 | 167 | 168 | 169 | )} 170 | 171 |

172 | ); 173 | } 174 | 175 | function onDeviceFailure(error: Error) { 176 | console.error(error); 177 | alert( 178 | "Error acquiring camera or microphone permissions. Please make sure you grant the necessary permissions in your browser and reload the tab" 179 | ); 180 | } 181 | -------------------------------------------------------------------------------- /components/CloseIcon.tsx: -------------------------------------------------------------------------------- 1 | export function CloseIcon() { 2 | return ( 3 | 11 | ); 12 | } 13 | -------------------------------------------------------------------------------- /components/NoAgentNotification.tsx: -------------------------------------------------------------------------------- 1 | import type { AgentState } from "@livekit/components-react"; 2 | import { useEffect, useRef, useState } from "react"; 3 | 4 | interface NoAgentNotificationProps extends React.PropsWithChildren