@vpalmisano/webrtcperf 4.6.2 → 4.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpalmisano/webrtcperf",
-  "version": "4.6.2",
+  "version": "4.7.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/vpalmisano/webrtcperf.git"
@@ -51,23 +51,24 @@
   },
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@google/genai": "^1.22.0",
-    "@puppeteer/browsers": "^2.10.10",
+    "@google/genai": "^1.46.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@puppeteer/browsers": "^2.13.0",
     "@vpalmisano/throttler": "0.0.14",
-    "@vpalmisano/webrtcperf-js": "^1.1.16",
-    "axios": "^1.12.2",
+    "@vpalmisano/webrtcperf-js": "^1.2.3",
+    "axios": "^1.13.5",
     "chalk-template": "^1.1.2",
     "change-case": "^4.1.2",
     "compression": "^1.8.1",
     "convict": "^6.2.4",
     "convict-format-with-validator": "^6.2.0",
     "debug-level": "^4.1.1",
-    "dockerode": "^4.0.9",
-    "express": "^5.1.0",
+    "dockerode": "^4.0.10",
+    "express": "^5.2.1",
     "express-basic-auth": "^1.2.1",
     "fast-stats": "^0.0.7",
     "form-data": "^4.0.4",
-    "googleapis": "^160.0.0",
+    "googleapis": "^164.1.0",
     "ipaddr.js": "^2.2.0",
     "json5": "^2.2.3",
     "lorem-ipsum": "^2.0.8",
@@ -78,16 +79,17 @@
     "pidtree": "^0.6.0",
     "pidusage": "^4.0.1",
     "prom-client": "^15.1.3",
-    "puppeteer": "^24.23.0",
-    "puppeteer-core": "^24.23.0",
+    "puppeteer": "^24.40.0",
+    "puppeteer-core": "^24.40.0",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "puppeteer-intercept-and-modify-requests": "^1.3.1",
     "sprintf-js": "^1.1.3",
     "tar-fs": "^3.1.1",
     "toml": "^3.0.0",
-    "ws": "^8.18.3",
-    "yaml": "^2.8.1"
+    "ws": "^8.20.0",
+    "yaml": "^2.8.1",
+    "zod": "3"
   },
   "devDependencies": {
     "@eslint/js": "^9.37.0",
@@ -122,7 +124,7 @@
     "ts-loader": "^9.5.4",
     "typedoc": "^0.28.13",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.45.0",
+    "typescript-eslint": "^8.46.2",
     "webpack": "^5.102.0",
     "webpack-cli": "^6.0.1",
     "webpack-node-externals": "^3.0.0",

package/src/app.ts

@@ -26,6 +26,7 @@ import { markedTerminal } from 'marked-terminal'
 import { EventEmitter } from 'events'
 import { runWithDocker } from './docker'
 import { plotDetailedStatsDashboard } from './plot'
+import { mcpRunner } from './mcp'
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { marked } = require('marked')
@@ -243,6 +244,7 @@ async function main(): Promise<void> {
     process.exit(0)
   }
 
+  // Handle plot command.
   if (process.argv.includes('--plot')) {
     process.argv = process.argv.filter(s => s !== '--plot')
     try {
@@ -254,6 +256,13 @@ async function main(): Promise<void> {
     process.exit(0)
   }
 
+  // Handle MCP command.
+  if (process.argv.includes('--mcp')) {
+    process.argv = process.argv.filter(s => s !== '--mcp')
+    await mcpRunner()
+    return
+  }
+
   let configs: Config[]
 
   // Handle prompt.

package/src/config.ts

@@ -1,4 +1,5 @@
 import convict, { addFormats, SchemaObj } from 'convict'
+import { z } from 'zod'
 import { ipaddress, url } from 'convict-format-with-validator'
 import { existsSync } from 'fs'
 import os from 'os'
@@ -472,8 +473,9 @@ the following global variables will be attached to the \`webrtcperf\` global obj
 \`WEBRTC_PERF_SESSION\` the session number (0-indexed); \
 \`WEBRTC_PERF_TAB\` the tab number inside the same session (0-indexed); \
 \`WEBRTC_PERF_INDEX\` the page absolute index (0-indexed).
-Suggested values:
-- With meet.google.com: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js
+Suggested values for automated testing:
+- meet.google.com: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js
+- meet.livekit.io: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/livekit.js
 `,
     format: String,
     default: '',
@@ -916,6 +918,40 @@ export function getConfigDocs(): ConfigDocs {
   return formatDocs({}, null, convict(configSchema).getSchema())
 }
 
+/**
+ * Returns a Zod schema for the config object, with all parameters optional and described.
+ * Uses the config default values when a field is omitted. Useful for MCP tools and other
+ * consumers that need validated partial config.
+ */
+export function getConfigZodSchema(): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const schema = convict(configSchema).getSchema()
+  const shape: Record<string, z.ZodTypeAny> = {}
+  for (const [key, value] of Object.entries(schema._cvtProperties)) {
+    const prop = value as SchemaObj & { doc?: string; format?: unknown; default?: unknown }
+    const doc = prop.doc ?? key
+    const def = prop.default
+    const format = prop.format
+    let zodType: z.ZodTypeAny
+    if (format === String || format === 'string') {
+      zodType = z.string()
+    } else if (format === 'nat' || format === Number) {
+      zodType = z.number()
+    } else if (format === 'float') {
+      zodType = z.number()
+    } else if (format === 'Boolean' || format === 'boolean') {
+      zodType = z.boolean()
+    } else if (format === 'index') {
+      zodType = z.union([z.string(), z.number(), z.boolean()])
+    } else if (Array.isArray(format)) {
+      zodType = z.enum(format as [string, ...string[]])
+    } else {
+      zodType = z.union([z.string(), z.number(), z.boolean()])
+    }
+    shape[key] = def !== undefined ? zodType.default(def).describe(doc) : zodType.optional().describe(doc)
+  }
+  return z.object(shape)
+}
+
 const _schemaProperties = convict(configSchema).getProperties()
 
 /** [[include:config.md]] */

package/src/mcp.ts

@@ -0,0 +1,248 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { getSessionThrottleIndex, startThrottle } from '@vpalmisano/throttler'
+import { z } from 'zod'
+
+import { loadConfig } from './config'
+import type { Config } from './config'
+import { Session } from './session'
+import { Stats } from './stats'
+import { MediaPath, prepareFakeMedia } from './media'
+import { logger } from './utils'
+
+const log = logger('webrtcperf:mcp')
+
+const mcpServer = new McpServer({
+  name: 'webrtcperf',
+  version: '1.0.0',
+})
+
+let stats: Stats
+let statsReady: Promise<void>
+
+async function getStats(): Promise<Stats> {
+  if (!stats) {
+    const [defaultConfig] = await loadConfig(undefined, {
+      showStats: false,
+    })
+    if (!defaultConfig.startTimestamp) {
+      defaultConfig.startTimestamp = Date.now()
+    }
+    stats = new Stats(defaultConfig)
+    stats.on('stats', () => {
+      mcpServer.server.sendResourceUpdated({ uri: 'webrtcperf://stats' })
+    })
+    statsReady = stats.start()
+  }
+  await statsReady
+  return stats
+}
+
+async function startSessionHandler(args: {
+  config: Record<string, unknown>
+}): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const { config } = args
+  log.debug('startSessionHandler', config)
+  const stats = await getStats()
+  const configs = await loadConfig(undefined, config as Partial<Config>)
+  const sessionConfig = configs[0]
+  const tabsPerSession = sessionConfig.tabsPerSession ?? 1
+  const id = stats.consumeSessionId(tabsPerSession)
+  const throttleIndex = getSessionThrottleIndex(id)
+  const spawnRate = (sessionConfig as Config & { spawnRate?: number }).spawnRate ?? 1
+  const spawnPeriod = 1000 / spawnRate
+  const throttleConfig = (sessionConfig as Config & { throttleConfig?: string }).throttleConfig
+  if (throttleConfig) {
+    await startThrottle(throttleConfig)
+  }
+  const mediaPaths: MediaPath[] = []
+  const videoPath = sessionConfig.videoPath
+  if (videoPath) {
+    for (const vp of videoPath.split(',')) {
+      const ret = await prepareFakeMedia({ ...sessionConfig, videoPath: vp })
+      mediaPaths.push(ret)
+    }
+  }
+  const mediaPath = mediaPaths.length ? mediaPaths[id % mediaPaths.length] : undefined
+
+  if (sessionConfig.url.startsWith('https://meet.google.com')) {
+    if (!sessionConfig.scriptPath) {
+      sessionConfig.scriptPath =
+        'https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js'
+    }
+    if (!sessionConfig.scriptParams) {
+      sessionConfig.scriptParams = '{"enableMic": true, "enableCam": true}'
+    }
+    if (!sessionConfig.debuggingPort) {
+      sessionConfig.debuggingPort = 9000
+    }
+  } else if (sessionConfig.url.startsWith('https://meet.livekit.io')) {
+    if (!sessionConfig.scriptPath) {
+      sessionConfig.scriptPath =
+        'https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/livekit.js'
+    }
+  }
+
+  const session = new Session({
+    ...sessionConfig,
+    throttleIndex,
+    spawnPeriod,
+    mediaPath,
+    id,
+  })
+  session.once('stop', () => {
+    setTimeout(() => startSessionHandler({ config }).catch(() => {}), spawnPeriod)
+  })
+  stats.addSession(session)
+  try {
+    await session.start()
+  } catch (err) {
+    stats.removeSession(session.id)
+    throw err
+  }
+  if (sessionConfig.runDuration) {
+    setTimeout(() => {
+      session.removeAllListeners()
+      session.stop()
+      stats.removeSession(session.id)
+    }, sessionConfig.runDuration * 1000)
+  }
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Session created', id }, null, 2),
+      },
+    ],
+  }
+}
+
+async function stopSessionHandler(args: { id: number }): Promise<{
+  content: Array<{ type: 'text'; text: string }>
+}> {
+  const { id } = args
+  log.debug('stopSessionHandler', id)
+  const s = await getStats()
+  const session = s.sessions.get(id)
+  if (!session) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ message: 'Session not found', id }, null, 2),
+        },
+      ],
+    }
+  }
+  session.removeAllListeners()
+  s.removeSession(id)
+  await session.stop()
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Session deleted', id }),
+      },
+    ],
+  }
+}
+
+async function getSessionsHandler(): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const s = await getStats()
+  const sessions = Array.from(s.sessions.entries()).map(([id, session]) => ({
+    id,
+    stats: session.stats,
+  }))
+  log.debug('getSessionsHandler', sessions)
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ sessions, count: sessions.length }),
+      },
+    ],
+  }
+}
+
+async function resetStatsHandler(): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const s = await getStats()
+  log.debug('resetStatsHandler')
+  s.resetStats()
+  await mcpServer.server.sendResourceUpdated({ uri: 'webrtcperf://stats' })
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Stats reset' }),
+      },
+    ],
+  }
+}
+
+async function getStatsReadHandler(uri: URL): Promise<{
+  contents: Array<{ uri: string; mimeType: string; text: string }>
+}> {
+  const stats = await getStats()
+  log.debug('getStatsReadHandler', uri.href)
+  return {
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(stats.collectedStats),
+      },
+    ],
+  }
+}
+
+mcpServer.registerTool(
+  'start_session',
+  {
+    description:
+      'Start a new webrtcperf session in-process. Config is the session config object (url, tabsPerSession, throttleConfig, etc.). Returns the created session id.',
+    inputSchema: { config: z.record(z.string(), z.unknown()) },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  startSessionHandler as any,
+)
+
+mcpServer.registerTool(
+  'stop_session',
+  {
+    description: 'Stop a webrtcperf session by id.',
+    inputSchema: { id: z.number().int().nonnegative() },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  stopSessionHandler as any,
+)
+
+mcpServer.registerTool(
+  'get_sessions',
+  {
+    description: 'List current webrtcperf sessions (id and stats for each running session).',
+  },
+  getSessionsHandler,
+)
+
+mcpServer.registerTool(
+  'reset_stats',
+  {
+    description: 'Reset the collected webrtcperf stats.',
+  },
+  resetStatsHandler,
+)
+
+mcpServer.registerResource(
+  'stats',
+  'webrtcperf://stats',
+  { description: 'Get the current webrtcperf stats.' },
+  getStatsReadHandler,
+)
+
+export async function mcpRunner(): Promise<void> {
+  log.debug('mcpRunner')
+  const transport = new StdioServerTransport()
+  await mcpServer.connect(transport)
+}

package/src/media.ts

@@ -10,7 +10,6 @@ export type MediaPath = {
   video: string
   audio: string
   mp4: string
-  m4a: string
 }
 
 /**
@@ -79,24 +78,19 @@ export async function prepareFakeMedia({
   const destMp4Path = useFakeMedia
     ? ''
     : `${videoCachePath}/${name}_${videoWidth}x${videoHeight}_${videoFramerate}fps.mp4`
-  const destM4aPath = useFakeMedia ? '' : `${videoCachePath}/${name}.m4a`
 
   if (
     !existsSync(destVideoPath) ||
     !existsSync(destAudioPath) ||
     (destMp4Path && !existsSync(destMp4Path)) ||
-    (destM4aPath && !existsSync(destM4aPath)) ||
     !videoCacheRaw
   ) {
-    log.info(
-      `Converting ${videoPath} to ${destVideoPath}, ${destAudioPath}${destMp4Path ? `, ${destMp4Path}` : ''}${destM4aPath ? `, ${destM4aPath}` : ''}`,
-    )
+    log.info(`Converting ${videoPath} to ${destVideoPath}, ${destAudioPath}${destMp4Path ? `, ${destMp4Path}` : ''}`)
     const destVideoPathTmp = `${videoCachePath}/${name}_${videoWidth}x${videoHeight}_${videoFramerate}fps.tmp.${videoFormat}`
     const destAudioPathTmp = `${videoCachePath}/${name}.tmp.wav`
     const destMp4PathTmp = useFakeMedia
       ? ''
       : `${videoCachePath}/${name}_${videoWidth}x${videoHeight}_${videoFramerate}fps.tmp.mp4`
-    const destM4aPathTmp = useFakeMedia ? '' : `${videoCachePath}/${name}.tmp.m4a`
 
     try {
       let source = `-i "${videoPath}"`
@@ -119,8 +113,8 @@ export async function prepareFakeMedia({
           ` ${videoMap} ${destVideoPathTmp}` +
           ` ${audioMap} -ar 48000 ${destAudioPathTmp}` +
           (destMp4PathTmp
-            ? ` ${videoMap} -c:v libx264 -crf 10 -f mp4 -movflags faststart ${destMp4PathTmp}` +
-              ` ${audioMap} -c:a aac -ar 48000 -b:a 192k -f mp4 -movflags faststart ${destM4aPathTmp}`
+            ? ` ${videoMap} -c:v libx264 -crf 10` +
+              ` ${audioMap} -c:a aac -ar 48000 -b:a 192k -f mp4 -movflags faststart ${destMp4PathTmp}`
             : ''),
       )
       await fs.rename(destVideoPathTmp, destVideoPath)
@@ -128,9 +122,6 @@ export async function prepareFakeMedia({
       if (destMp4PathTmp) {
         await fs.rename(destMp4PathTmp, destMp4Path)
       }
-      if (destM4aPathTmp) {
-        await fs.rename(destM4aPathTmp, destM4aPath)
-      }
     } catch (err) {
       log.error(`Error converting video: ${(err as Error).stack}`)
       fs.unlink(destVideoPathTmp).catch(e => log.debug(e.message))
@@ -146,6 +137,5 @@ export async function prepareFakeMedia({
     video: destVideoPath,
     audio: destAudioPath,
     mp4: destMp4Path,
-    m4a: destM4aPath,
   }
 }

package/src/rtcstats.ts

@@ -81,6 +81,7 @@ export enum PageStatsNames {
   screenStartFrameDelay = 'screenStartFrameDelay',
 
   cpuPressure = 'cpuPressure',
+  questionAnswerDelay = 'questionAnswerDelay',
 
   videoWidth = 'videoWidth',
   videoHeight = 'videoHeight',

package/src/session.ts

@@ -86,6 +86,7 @@ declare global {
       screenStartFrameDelay: number
     }
     collectCpuPressure: () => number
+    collectQuestionAnswerDelay: () => number
     collectVideoStats: () => {
       width: number
       height: number
@@ -817,16 +818,19 @@ try {
   console.error('[webrtcperf] Error parsing scriptParams:', err);
   webrtcperf.params = {};
 };
+
+const webrtcperf_getServerUrl = (path, protocol = 'http', query = '') => {
+  return protocol + "${this.serverUseHttps ? 's' : ''}://localhost:${this.serverPort}/" + path + "?auth=${this.serverSecret}" + (query ? "&" + query : '')
+}
   `
 
     if (this.serverPort) {
       cmd += `\
-webrtcperf.config.SAVE_MEDIA_URL = "ws${this.serverUseHttps ? 's' : ''}://localhost:${this.serverPort}/?auth=${this.serverSecret}&action=write-stream";
+webrtcperf.config.SAVE_MEDIA_URL = webrtcperf_getServerUrl("", "ws", "action=write-stream");
     `
       if (this.mediaPath?.mp4 && !this.useFakeMedia) {
         cmd += `\
-webrtcperf.config.VIDEO_URL = "http${this.serverUseHttps ? 's' : ''}://localhost:${this.serverPort}/cache/${path.basename(this.mediaPath.mp4)}?auth=${this.serverSecret}";
-webrtcperf.config.AUDIO_URL = "http${this.serverUseHttps ? 's' : ''}://localhost:${this.serverPort}/cache/${path.basename(this.mediaPath.m4a)}?auth=${this.serverSecret}";
+webrtcperf.config.MEDIA_URL = webrtcperf_getServerUrl("cache/${path.basename(this.mediaPath.mp4)}");
     `
       }
     }
@@ -1710,6 +1714,7 @@ mv ${logFilePath}.tmp ${logFilePath};
     const pageCpu: Record<string, number> = {}
     const pageMemory: Record<string, number> = {}
     const cpuPressureStats: Record<string, number> = {}
+    const questionAnswerDelayStats: Record<string, number> = {}
 
     const videoWidth: Record<string, number> = {}
     const videoHeight: Record<string, number> = {}
@@ -1738,6 +1743,7 @@ mv ${logFilePath}.tmp ${logFilePath};
             audioEndToEndDelay,
             videoEndToEndDelay,
             cpuPressure,
+            questionAnswerDelay,
             videoStats,
             customMetrics,
           } = await page.evaluate(async () => ({
@@ -1745,6 +1751,7 @@ mv ${logFilePath}.tmp ${logFilePath};
             audioEndToEndDelay: webrtcperf.collectAudioEndToEndStats(),
             videoEndToEndDelay: webrtcperf.collectVideoEndToEndStats(),
             cpuPressure: webrtcperf.collectCpuPressure(),
+            questionAnswerDelay: webrtcperf.collectQuestionAnswerDelay(),
             videoStats: webrtcperf.collectVideoStats(),
             customMetrics: 'collectCustomMetrics' in window ? collectCustomMetrics() : null,
           }))
@@ -1811,6 +1818,7 @@ mv ${logFilePath}.tmp ${logFilePath};
           }
 
           if (cpuPressure !== undefined) cpuPressureStats[pageKey] = cpuPressure
+          if (questionAnswerDelay !== undefined) questionAnswerDelayStats[pageKey] = questionAnswerDelay
           if (videoStats) {
             videoWidth[pageKey] = videoStats.width
             videoHeight[pageKey] = videoStats.height
@@ -1912,6 +1920,7 @@ mv ${logFilePath}.tmp ${logFilePath};
       wsRecvBytes: wsRecvBytesStats,
       wsRecvLatency: wsRecvLatencyStats,
       cpuPressure: cpuPressureStats,
+      questionAnswerDelay: questionAnswerDelayStats,
       videoWidth,
       videoHeight,
       videoBufferedTime,

package/src/stats.ts

@@ -1682,6 +1682,15 @@ export class Stats extends events.EventEmitter {
     }
   }
 
+  /**
+   * Reset the stats.
+   */
+  resetStats(): void {
+    log.debug('resetStats')
+    this.collectedStats = this.initCollectedStats()
+    this.externalCollectedStats.clear()
+  }
+
   async stop() {
     if (!this.running) return
     this.running = false
@@ -1716,7 +1725,6 @@ export class Stats extends events.EventEmitter {
       this.metrics = {}
     }
 
-    this.collectedStats = this.initCollectedStats()
-    this.externalCollectedStats.clear()
+    this.resetStats()
   }
 }