browser ──wss://app.example.com/api/stt/listen──▶ Next.js / NestJS / NGINX
                                                          │ validate session
                                                          │ inject service token
                                              ws://127.0.0.1:4600/v1/listen/dg

'use client';

export type SttFrame =
  | { type: 'Metadata'; transaction_key: string; request_id: string; sha256: string; created: string; duration: number; channels: number; models: string[] }
  | { type: 'Results'; channel: { alternatives: { transcript: string; confidence: number; words: Array<{ word: string; start: number; end: number; confidence: number; punctuated_word: string; speaker: number }> }[] }; is_final: boolean; speech_final: boolean; from_finalize: boolean; start: number; duration: number; metadata: { request_id: string } }
  | { type: 'SpeechStarted'; channel: number[]; timestamp: number }
  | { type: 'UtteranceEnd'; channel: number[]; last_word_end: number };

export interface SttHandle {
  sendPcm: (pcm: Int16Array) => void;
  close: () => void;
}

export async function openSttSocket(opts: {
  url: string; // wss://app.example.com/api/stt/listen
  language: 'en' | 'fr' | 'de' | 'it';
  onFrame: (frame: SttFrame) => void;
}): Promise<SttHandle> {
  const params = new URLSearchParams({
    model: 'nova-2',
    language: opts.language,
    encoding: 'linear16',
    sample_rate: '16000',
    channels: '1',
    interim_results: 'true',
    punctuate: 'true',
    words: 'true',
  });
  const ws = new WebSocket(`${opts.url}?${params.toString()}`);
  ws.binaryType = 'arraybuffer';
  await new Promise<void>((resolve, reject) => {
    ws.addEventListener('open', () => resolve(), { once: true });
    ws.addEventListener('error', (e) => reject(e), { once: true });
  });
  ws.addEventListener('message', (ev) => {
    if (typeof ev.data !== 'string') return;
    try { opts.onFrame(JSON.parse(ev.data) as SttFrame); } catch { /* ignore */ }
  });
  const keepalive = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'KeepAlive' }));
  }, 5000);
  return {
    sendPcm: (pcm) => { if (ws.readyState === WebSocket.OPEN) ws.send(pcm.buffer); },
    close: () => {
      clearInterval(keepalive);
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: 'CloseStream' }));
        ws.close(1000);
      }
    },
  };
}

import { createServer } from 'node:http';
import { WebSocketServer, WebSocket } from 'ws';
import next from 'next';
import { parse } from 'node:url';

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
await app.prepare();
const handle = app.getRequestHandler();
const server = createServer((req, res) => handle(req, res, parse(req.url, true)));
const wss = new WebSocketServer({ noServer: true });

server.on('upgrade', async (req, sock, head) => {
  const { pathname, search } = parse(req.url ?? '/', true);
  if (pathname !== '/api/stt/listen') { sock.destroy(); return; }
  const ok = await validateSession(req.headers.cookie ?? '');
  if (!ok) { sock.write('HTTP/1.1 401 Unauthorized\r\n\r\n'); sock.destroy(); return; }
  wss.handleUpgrade(req, sock, head, (clientWs) => {
    const upstreamUrl = `ws://127.0.0.1:4600/v1/listen/dg${search ?? ''}`;
    const upstream = new WebSocket(upstreamUrl, {
      headers: { Authorization: `Token ${process.env.STT_SERVICE_TOKEN ?? 'dummy'}` },
    });
    upstream.on('open', () => {
      clientWs.on('message', (data) => upstream.send(data));
      upstream.on('message', (data) => clientWs.send(data));
    });
    const close = () => { try { clientWs.close(1000); } catch {}; try { upstream.close(1000); } catch {}; };
    clientWs.on('close', close); upstream.on('close', close);
    clientWs.on('error', close); upstream.on('error', close);
  });
});

server.listen(Number(process.env.PORT ?? 3000));

async function validateSession(cookieHeader) { return cookieHeader.includes('session='); }

import { OnGatewayConnection, OnGatewayDisconnect, WebSocketGateway, WebSocketServer } from '@nestjs/websockets';
import { Server, WebSocket } from 'ws';
import { IncomingMessage } from 'node:http';

@WebSocketGateway({ path: '/api/stt/listen', cors: { origin: true } })
export class SttProxyGateway implements OnGatewayConnection, OnGatewayDisconnect {
  @WebSocketServer() server!: Server;
  private bridges = new WeakMap<WebSocket, WebSocket>();

  async handleConnection(client: WebSocket, req: IncomingMessage): Promise<void> {
    if (!(await this.validateSession(req))) { client.close(1008, 'auth-missing'); return; }
    const search = req.url?.split('?')[1] ?? '';
    const upstream = new WebSocket(`ws://127.0.0.1:4600/v1/listen/dg?${search}`, {
      headers: { Authorization: `Token ${process.env.STT_SERVICE_TOKEN ?? 'dummy'}` },
    });
    this.bridges.set(client, upstream);
    upstream.on('open', () => {
      client.on('message', (data) => upstream.send(data));
      upstream.on('message', (data) => client.send(data));
    });
    const close = () => { try { client.close(1000); } catch {}; try { upstream.close(1000); } catch {}; };
    client.on('close', close); upstream.on('close', close);
    client.on('error', close); upstream.on('error', close);
  }
  handleDisconnect(client: WebSocket): void {
    this.bridges.get(client)?.close(1000); this.bridges.delete(client);
  }
  private async validateSession(req: IncomingMessage): Promise<boolean> {
    return Boolean(req.headers.cookie?.includes('session='));
  }
}

// main.ts — register WsAdapter
import { WsAdapter } from '@nestjs/platform-ws';
const app = await NestFactory.create(AppModule);
app.useWebSocketAdapter(new WsAdapter(app));

from __future__ import annotations
import asyncio, json
from pathlib import Path
import websockets

STT_URL = "ws://127.0.0.1:4600/v1/listen/dg"

async def transcribe_file(path: Path, language: str = "en") -> str:
    pcm = path.read_bytes()  # 16k mono int16 headerless
    qs = (
        "?model=nova-2"
        f"&language={language}"
        "&encoding=linear16&sample_rate=16000&channels=1"
        "&punctuate=true&words=true"
    )
    finals: list[str] = []
    async with websockets.connect(
        STT_URL + qs,
        max_size=2**24,
        additional_headers=[("Authorization", "Token dummy")],
    ) as ws:
        async def consumer() -> None:
            async for msg in ws:
                if not isinstance(msg, str):
                    continue
                frame = json.loads(msg)
                if frame.get("type") == "Results" and frame.get("is_final"):
                    finals.append(frame["channel"]["alternatives"][0]["transcript"])

        consumer_task = asyncio.create_task(consumer())
        for i in range(0, len(pcm), 2048):  # ~64 ms frames
            await ws.send(pcm[i:i + 2048])
        await ws.send(json.dumps({"type": "CloseStream"}))
        try:
            await asyncio.wait_for(consumer_task, timeout=30)
        except TimeoutError:
            consumer_task.cancel()
    return " ".join(finals).strip()

server {
  listen 443 ssl http2;
  server_name app.example.com;
  ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

  location /api/stt/listen {
    auth_request /api/_auth_check;
    proxy_pass http://127.0.0.1:4600/v1/listen/dg;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header Authorization "Token $stt_service_token";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
  }

  location = /api/_auth_check {
    internal;
    proxy_pass http://127.0.0.1:3000/api/auth/check;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
  }
}