buzz-media-attachments

Buzz Media Attachments

Use this workflow when a user asks to post a local media file into the current Buzz conversation and normal MEDIA:/path delivery fails.

Workflow

1. Verify the source file exists and is readable. Use ffprobe for video metadata when relevant.

2. Find the current Buzz channel UUID from the live gateway log rather than guessing:

   # Search ~/.hermes/logs/gateway.log for the user's latest inbound Buzz message.
   # The line contains: platform=buzz ... chat=<CHANNEL_UUID>
   

3. Use Buzz's native attachment mechanism:

   buzz messages send \
     --channel <CHANNEL_UUID> \
     --content - \
     --file /absolute/path/to/file
   

   --file may be repeated to attach several files to one message.

4. Load Buzz credentials without shell-sourcing .env. BUZZ_AUTH_TAG can contain JSON that shell source mangles. Parse the file with python-dotenv and pass values through a subprocess environment:

   import os, subprocess
   from dotenv import dotenv_values
   
   env = os.environ.copy()
   env.update({
       k: v for k, v in dotenv_values(os.path.expanduser("~/.hermes/.env")).items()
       if v is not None
   })
   result = subprocess.run(
       ["buzz", "messages", "send",
        "--channel", channel_id,
        "--content", "-",
        "--file", file_path],
       input=caption,
       text=True,
       env=env,
       capture_output=True,
       timeout=180,
   )
   

5. If Buzz rejects an MP4, diagnose the returned relay error:

   • moov atom not at front of file (not fast-start): first try remuxing:

     ffmpeg -y -v error -i input.mp4 -c copy -movflags +faststart output.mp4
     

   • media contains metadata or a non-canonical metadata channel: use Buzz Desktop's canonical sanitizer settings. A simple stream-copy remux is insufficient because FFmpeg may retain or add forbidden MP4 metadata structures. Fully re-encode exactly as follows: