🎤 Micdrop

Getting Started

Get up and running with Micdrop to build real-time voice conversations with AI agents.

Quick Setup

Client (Browser)

Install the browser package and start capturing voice input:

Terminal window
npm install @micdrop/web

If you’re using React, you can also install @micdrop/react package to get a ready-to-use React hooks.

import { Micdrop } from '@micdrop/web'


// Start a voice conversation
Micdrop.start({
  url: 'ws://localhost:8081',
})


// Listen for events
Micdrop.on('StateChange', (state) => {
  console.log('Conversation:', state.conversation)
  console.log('isAssistantSpeaking:', state.isAssistantSpeaking)
})


Micdrop.on('EndCall', () => {
  console.log('Call ended by assistant')
})

Client (React Native)

The same call runs on a phone, against the same server:

Terminal window
npm install @micdrop/react-native react-native-audio-api
import { Micdrop, useMicdropState } from '@micdrop/react-native'


function Call() {
  const state = useMicdropState()


  return (
    <Button
      title={state.isStarted ? 'Hang up' : 'Start the call'}
      onPress={() =>
        state.isStarted
          ? Micdrop.stop()
          : Micdrop.start({ url: 'ws://localhost:8081' })
      }
    />
  )
}

Audio goes through native code there, see React Native for the setup.

Server (Node.js)

Install the server package and set up AI integrations:

Terminal window
npm install @micdrop/server @micdrop/openai @micdrop/gladia @micdrop/elevenlabs

This example uses OpenAI, Gladia and ElevenLabs. You can use other providers with a provided or custom integrations.

import { MicdropServer } from '@micdrop/server'
import { OpenaiAgent } from '@micdrop/openai'
import { GladiaSTT } from '@micdrop/gladia'
import { ElevenLabsTTS } from '@micdrop/elevenlabs'
import { WebSocketServer } from 'ws'


const wss = new WebSocketServer({ port: 8081 })


wss.on('connection', (socket) => {
  // Handle voice conversation
  new MicdropServer(socket, {
    firstMessage: 'How can I help you today?',


    agent: new OpenaiAgent({
      apiKey: process.env.OPENAI_API_KEY,
      systemPrompt: 'You are a helpful assistant',
    }),


    stt: new GladiaSTT({
      apiKey: process.env.GLADIA_API_KEY,
    }),


    tts: new ElevenLabsTTS({
      apiKey: process.env.ELEVENLABS_API_KEY,
      voiceId: process.env.ELEVENLABS_VOICE_ID,
    }),
  })
})

Don’t forget to set the API keys in the environment variables.

Demos

See Micdrop in action:

  • Basic Example - The shortest way to hear Micdrop work: one button, one WebSocket server, OpenAI for the agent, the transcription and the voice. Around 150 lines to read.
  • Dictation Example - A call with ears only, filling a text area as you speak, in the language picked at the top of the page
  • Advanced Example - React client and Fastify server in one folder, with every provider wired in and picked from the browser
  • World Demo - Immersive 3D demo where a newborn planet talks to you and reshapes itself as the conversation goes
  • Form Demo - A demo app showcasing Micdrop’s capabilities for voice-assisted form filling using OpenAI and tool calling.

Setup Documentation MCP

To vibe code your Micdrop implementation faster with Cursor, Claude Code or any other agent, install Context7 MCP.

Once the MCP is installed, you can prompt like this:

create a turbo monorepo in current folder with a client and a server in a new /apps folder:
- server: a simple fastify server with Typescript that implements a micdrop server (use context7)
- client: a simple React webapp with micdrop client. show play/stop/pause buttons and conversation, no other UI. make it beautiful and futuristic.

Troubleshooting

Microphone not working?

  • Check browser permissions for microphone access
  • Ensure you’re serving over HTTPS in production

WebSocket connection fails?

  • Verify the server is running on the correct port
  • Check firewall settings

AI responses not working?

  • Verify all API keys are set correctly
  • Check the server console for error messages