Skip to content

README.md

Latest commit

 

History

History
174 lines (130 loc) · 4.31 KB

README.md

File metadata and controls

174 lines (130 loc) · 4.31 KB

Fireflies.ai Proxy Service

A Node.js service that provides a REST API to start and monitor real-time transcriptions from Fireflies.ai.

Features

  • Start a real-time transcription session for a Fireflies.ai meeting
  • Monitor the status of transcription requests
  • Store transcription data in Supabase
  • Automatic reconnection handling for WebSocket connections
  • Configurable buffering of transcription chunks
  • Manually stop an active transcription session via API
  • Automatic 10-minute inactivity timer to stop sessions if no speech is detected from Fireflies

Prerequisites

  • Node.js 16.x or later
  • npm or yarn
  • Supabase account and project
  • Fireflies.ai API key with access to the Realtime API

Setup

  1. Clone the repository
  2. Install dependencies: 
    npm install
  3. Copy .env.example to .env and update the values: 
    cp .env.example .env
  4. Update the .env file with your Supabase and Fireflies.ai credentials

Environment Variables

Variable Description Required Default
PORT Port to run the server on No 3000
NODE_ENV Node environment No development
SUPABASE_URL Supabase project URL Yes
SUPABASE_ANON_KEY Supabase anonymous key Yes
SUPABASE_SERVICE_ROLE_KEY Supabase service role key Yes
FIREFLIES_API_KEY Fireflies.ai API key Yes
LOG_LEVEL Logging level No info

API Endpoints

Start a Transcription

POST /api/transcription/start

Initiates a real-time transcription for the given Fireflies.ai transcriptionId.

Request Body:

{
  "transcriptionId": "your-fireflies-transcription-id",
  "requestId": "your-optional-client-provided-uuid" 
}
  • transcriptionId (string, required): The transcription ID from Fireflies.ai.
  • requestId (string, optional): A client-provided UUID for the request. If not provided, the server will generate one.

Success Response (202):

{
  "requestId": "server-generated-or-client-provided-uuid",
  "status": "processing",
  "message": "Transcription process initiated successfully."
}

Get Transcription Status

GET /api/transcription/status/:requestId

Retrieves the current status and content of a transcription request.

URL Parameters:

  • requestId (string, required): The ID of the transcription request (returned by the /start endpoint).

Success Response (200):

{
  "requestId": "unique-request-id",
  "status": "processing", // or "completed", "error"
  "content": "Transcription content...",
  "error": null, // or an error message string
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:01:00.000Z"
}

Stop a Transcription

POST /api/transcription/stop

Manually stops an active transcription session.

Request Body:

{
  "requestId": "unique-request-id-from-start"
}
  • requestId (string, required): The ID of the transcription request to stop (returned by the /start endpoint).

Success Response (200):

{
  "requestId": "unique-request-id-from-start",
  "status": "completed",
  "message": "Transcription session stopped successfully."
}

Database Schema

transcription_requests

Column Type Description
id UUID Primary key
transcription_id TEXT Fireflies.ai transcription ID
status TEXT Current status (processing/completed/error)
content TEXT Transcription content
error_message TEXT Error message if status is error
created_at TIMESTAMP When the request was created
updated_at TIMESTAMP When the request was last updated
last_event_at TIMESTAMP When the last event was received

Running the Application

Development

npm run dev

Production

npm run build
npm start

Deployment

This service is designed to be deployed as a long-running process. It is not suitable for serverless environments due to the persistent WebSocket connection requirement.

Recommended deployment options:

  • Containerized deployment (Docker) on platforms like:
    • Google Cloud Run (with CPU always allocated)
    • AWS ECS/Fargate
    • Azure Container Instances
    • DigitalOcean App Platform
  • Traditional VM/Server (e.g., AWS EC2, Google Compute Engine)

License

MIT