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:

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:

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:

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.

Examples

To hear Micdrop work, start with the basic example. Every other example app and demo, with the command that runs it, is listed in Examples and demos.

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