Audio / Voice Notes

क्या काम करता है

  • Media understanding (audio): यदि audio understanding enabled है (या auto‑detected), तो Mayros:
    1. पहला audio attachment (local path या URL) locate करता है और यदि आवश्यक हो तो इसे download करता है।
    2. प्रत्येक model entry को भेजने से पहले maxBytes enforce करता है।
    3. क्रम में पहली eligible model entry चलाता है (provider या CLI)।
    4. यदि यह fail या skip करता है (size/timeout), तो यह अगली entry try करता है।
    5. Success पर, यह Body को [Audio] block से replace करता है और {{Transcript}} set करता है।
  • Command parsing: जब transcription succeed होता है, तो CommandBody/RawBody को transcript पर सेट किया जाता है ताकि slash commands अभी भी काम करें।
  • Verbose logging: --verbose में, हम log करते हैं कि transcription कब चलता है और कब यह body को replace करता है।

Auto-detection (डिफ़ॉल्ट)

यदि आप models कॉन्फ़िगर नहीं करते और tools.media.audio.enabled false पर सेट नहीं है, तो Mayros इस क्रम में auto-detect करता है और पहले working विकल्प पर रुकता है:

  1. Local CLIs (यदि installed हैं)
    • sherpa-onnx-offline (SHERPA_ONNX_MODEL_DIR की आवश्यकता, encoder/decoder/joiner/tokens के साथ)
    • whisper-cli (whisper-cpp से; WHISPER_CPP_MODEL या bundled tiny model का उपयोग करता है)
    • whisper (Python CLI; models स्वचालित रूप से download करता है)
  2. Gemini CLI (gemini) read_many_files का उपयोग करके
  3. Provider keys (OpenAI → Groq → Deepgram → Google)

Auto-detection को disable करने के लिए, tools.media.audio.enabled: false सेट करें। Customize करने के लिए, tools.media.audio.models सेट करें। नोट: Binary detection macOS/Linux/Windows पर best-effort है; सुनिश्चित करें कि CLI PATH पर है (हम ~ expand करते हैं), या explicit CLI model को full command path के साथ सेट करें।

Config उदाहरण

Provider + CLI fallback (OpenAI + Whisper CLI)

json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
            timeoutSeconds: 45,
          },
        ],
      },
    },
  },
}

Provider-only with scope gating

json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Provider-only (Deepgram)

json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

नोट्स और limits

  • Provider auth standard model auth order का पालन करता है (auth profiles, env vars, models.providers.*.apiKey)।
  • Deepgram DEEPGRAM_API_KEY pick करता है जब provider: "deepgram" का उपयोग किया जाता है।
  • Deepgram setup विवरण: Deepgram (audio transcription)।
  • Audio providers baseUrl, headers, और providerOptions को tools.media.audio के माध्यम से override कर सकते हैं।
  • डिफ़ॉल्ट size cap 20MB (tools.media.audio.maxBytes) है। Oversize audio उस model के लिए skip किया जाता है और अगली entry try की जाती है।
  • Audio के लिए डिफ़ॉल्ट maxChars unset है (full transcript)। Output trim करने के लिए tools.media.audio.maxChars या per-entry maxChars सेट करें।
  • OpenAI auto डिफ़ॉल्ट gpt-4o-mini-transcribe है; उच्च accuracy के लिए model: "gpt-4o-transcribe" सेट करें।
  • tools.media.audio.attachments का उपयोग करके कई voice notes process करें (mode: "all" + maxAttachments)।
  • Transcript templates के लिए {{Transcript}} के रूप में उपलब्ध है।
  • CLI stdout capped है (5MB); CLI output संक्षिप्त रखें।

Groups में Mention Detection

जब किसी group chat के लिए requireMention: true सेट हो, तो Mayros अब mentions की जांच करने से पहले audio transcribe करता है। यह voice notes को तब भी process करने की अनुमति देता है जब उनमें mentions हों।

यह कैसे काम करता है:

  1. यदि किसी voice message में कोई text body नहीं है और group mentions की आवश्यकता है, तो Mayros एक "preflight" transcription करता है।
  2. Transcript को mention patterns (जैसे @BotName, emoji triggers) के लिए check किया जाता है।
  3. यदि एक mention मिलता है, तो संदेश पूर्ण reply pipeline के माध्यम से आगे बढ़ता है।
  4. Transcript का उपयोग mention detection के लिए किया जाता है ताकि voice notes mention gate पास कर सकें।

Fallback व्यवहार:

  • यदि preflight के दौरान transcription fail होता है (timeout, API error, आदि), तो संदेश को केवल text-only mention detection के आधार पर process किया जाता है।
  • यह सुनिश्चित करता है कि mixed messages (text + audio) कभी भी गलती से drop नहीं किए जाते।

उदाहरण: एक user Telegram group में एक voice note भेजता है जिसमें "Hey @Claude, what's the weather?" कहा गया है और requireMention: true है। Voice note transcribed है, mention detected है, और agent reply करता है।

सावधानियां

  • Scope rules first-match wins का उपयोग करते हैं। chatType को direct, group, या room में normalized किया जाता है।
  • सुनिश्चित करें कि आपका CLI exit 0 करे और plain text print करे; JSON को jq -r .text के माध्यम से massage करने की आवश्यकता है।
  • Timeouts reasonable रखें (timeoutSeconds, डिफ़ॉल्ट 60s) ताकि reply queue block न हो।
  • Preflight transcription mention detection के लिए केवल पहला audio attachment process करता है। अतिरिक्त audio main media understanding phase के दौरान process किया जाता है।