Media - Ravi

This page covers every media command in Ravi: what each one needs, what it prints, and how its output reaches a conversation. At the end you will be able to generate audio and images, send any file into a chat, and read the files people send to your agent.

Before you start

Put API keys in ~/.ravi/.env (open it with ravi daemon env), then restart the daemon so it picks them up:

ravi daemon restart -m "media keys added"

Feature	Keys	System tools
Audio generation	`ELEVENLABS_API_KEY` (optional `ELEVENLABS_VOICE_ID`)	`ffmpeg` to turn audio into a voice note
Transcription	`GROQ_API_KEY` or `OPENAI_API_KEY`	`ffmpeg` and `ffprobe` for audio longer than 10 minutes
Image generation	`OPENAI_API_KEY` or `GEMINI_API_KEY`	none
Video analysis	`GEMINI_API_KEY`	`yt-dlp` for YouTube subtitles
Sending to WhatsApp	none (uses your Omni setup)	the `omni` CLI on `PATH`

Install the system tools with brew install ffmpeg yt-dlp (macOS) or your Linux package manager. Two rules apply to every command below:

Generating is immediate. Delivering to a chat is not. Anything that posts into a conversation (--send, ravi media send, ravi stickers send) is a dry-run without --execute: it prints the plan and exits with code 3. Add --execute to send.
“The current chat” means the chat of the session that runs the command. When your agent runs --send while answering a Slack thread or a WhatsApp group, the file goes back there. From your own terminal there is no current chat, so use ravi media send with explicit --to and --account.

On Slack, files are uploaded natively through the Slack Web API into the same channel or thread. On WhatsApp (and other Omni channels), Ravi calls omni send and reports success only after Omni accepts the request.

Audio generation (text to speech)

Ravi turns text into speech with ElevenLabs.

# Generate an MP3 in the system temp directory
ravi audio generate "Hello, this is a test message"

# Pick a voice, speed and language
ravi audio generate "Bom dia a todos" --voice JBFqnCBsd6RMkjVDRZzb --speed 1.2 --lang pt

# Read the text from a file (relative .md or .txt path)
ravi audio generate --text-file notes/update.md

# Generate and send to the current chat as a voice note
ravi audio generate "Voice message content" --send --execute

# Same, with your own caption
ravi audio generate "Important update" --send --caption "Listen to this" --execute

# Faster model, custom output directory
ravi audio generate "Quick response" --model eleven_turbo_v2_5 -o ./audio

# List the voices on your ElevenLabs account
ravi audio voices --search narrator

Flag	Description	Default
`[text]` or `--text-file <path>`	Text to speak (one or the other)	required
`--voice <id>`	ElevenLabs voice ID	agent `tts_voice`, then `ELEVENLABS_VOICE_ID`, then a built-in voice
`--model <model>`	`eleven_multilingual_v2`, `eleven_turbo_v2_5`, …	agent `tts_model`, then `eleven_multilingual_v2`
`--speed <speed>`	0.5 to 2.0	agent `tts_speed`, then the voice default
`--lang <code>`	Language hint (`pt`, `en`, `es`, …)	agent `tts_lang`, then `pt-br`
`--format <fmt>`	`mp3_44100_128`, `mp3_22050_32`, `pcm_16000`	`mp3_44100_128`
`-o, --output <path>`	Output directory	system temp directory
`--send`	Send to the current chat	off
`--caption <text>`	Caption when sending	first 100 characters of the text
`--execute`	Confirm delivery when `--send` is used	off (dry-run)
`--json`	Print the JSON result	off

The language defaults to Portuguese (pt-br). Pass --lang en for English, or set tts_lang in the agent defaults (see Defaults).

Output:

Generating audio...

✓ Audio saved: /tmp/ravi-audio-1760013000000.mp3
  Send to chat: ravi media send "/tmp/ravi-audio-1760013000000.mp3" --execute

Text: Hello, this is a test message

With --send, Ravi converts the MP3 to OGG/Opus (64 kbps, 48 kHz, mono) with ffmpeg and sends the .ogg. WhatsApp shows it as a voice note; Slack shows it as an audio file. If ffmpeg is missing or fails, the MP3 is sent as a regular audio file.

Transcription

Ravi transcribes audio with Whisper. It uses Groq when GROQ_API_KEY is set, otherwise OpenAI. There is no fallback between them: if the chosen provider fails, the transcription fails.

Order	Provider	Model
1	Groq (`GROQ_API_KEY`)	`whisper-large-v3-turbo`
2	OpenAI (`OPENAI_API_KEY`)	`whisper-1`

ravi transcribe file ./recording.ogg
ravi transcribe file ./meeting.mp3 --lang en
ravi transcribe file ./meeting.mp3 --lang en --json

--lang defaults to pt. Supported formats: .ogg, .opus, .mp3, .m4a, .mp4, .wav, .webm. Audio longer than 10 minutes is split with ffmpeg into 10-minute chunks that overlap by 15 seconds, transcribed chunk by chunk and joined.

Transcribing /home/you/recording.ogg (audio/ogg)...

✓ Transcribed (45s)

The transcribed text appears here...

Voice messages your agent receives

Voice notes and audio files that arrive on Slack or WhatsApp are transcribed automatically, and the transcript goes into the agent’s prompt (see Files people send to your agent). This uses the same provider order, with Portuguese (pt) as the language hint. There is no setting to change that hint today; for audio in another language, transcribe the saved file again with ravi transcribe file <path> --lang <code>.

Image generation

Ravi generates and edits images with OpenAI or Gemini.

Choose a provider first

There is no built-in default provider. Without one, ravi image generate fails with IMAGE_PROVIDER_NOT_CONFIGURED. Set a global default once:

ravi settings set image.provider openai     # or gemini

Ravi picks each value in this order: the command flag, the agent defaults, the instance defaults, the global setting (image.provider, image.model, image.mode, image.quality, image.format), then the environment (RAVI_IMAGE_PROVIDER, RAVI_IMAGE_MODEL). If the selected provider fails, the command fails; retry with another --provider yourself.

Provider	Key	Default model	Model override
`openai`	`OPENAI_API_KEY`	`gpt-image-2`	`--model`, or `OPENAI_IMAGE_MODEL`
`gemini`	`GEMINI_API_KEY`	`gemini-3.1-flash-image-preview` (`--mode fast`), `gemini-3-pro-image-preview` (`--mode quality`)	`--model`, or `GEMINI_IMAGE_MODEL`

Generate

# Queue a generation (returns at once)
ravi image generate "a purple cat floating in space" --provider openai

# Wait for the result instead
ravi image generate "product photo of sneakers" --provider gemini --mode quality --sync

# Aspect ratio and size
ravi image generate "mountain landscape at sunset" --aspect 16:9 --size 4K

# Edit or reference an existing image (PNG, JPEG, WebP, GIF)
ravi image generate "turn this photo into a watercolor painting" --source ./photo.jpg

# Generate and send to the current chat
ravi image generate "coffee shop interior" --send --execute

Generation is asynchronous by default. The command records an image artifact, starts a background worker and prints:

✓ Image generation queued: art_...
  Hint: No polling needed: this artifact emits lifecycle events. Use events only for manual inspection or debugging.
  Debug: ravi artifacts show art_...

ravi artifacts show <id> gives the file path once the artifact is completed. When the command runs inside a session, that session is told when the image completes or fails, so the agent does not need to poll. With --sync, the command waits and prints the result:

✓ Image saved: /tmp/ravi-image-1760013000000.png
  Artifact: art_...
  Send to chat: ravi media send "/tmp/ravi-image-1760013000000.png" --execute

Prompt: product photo of sneakers
Provider: gemini | Model: gemini-3-pro-image-preview | Mode: quality | Aspect: auto | Size: auto

When the command runs in a session that belongs to a chat, the image is always sent back to that chat when it is ready, even without --send. That is why your agent needs --execute there. ravi image generate has no target flags; to send an image anywhere else, generate it and use ravi media send.

Flag	Description	Default
`--provider <provider>`	`openai` or `gemini`	see the order above
`--model <model>`	Provider model	provider default
`--mode <type>`	`fast` or `quality` (picks the Gemini model)	`fast`
`--source <path>`	Image to edit or use as reference	none
`--aspect <ratio>`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`	provider default
`--size <size>`	`1K`, `2K`, `4K`	provider default
`--quality <quality>`	OpenAI: `low`, `medium`, `high`, `auto`	provider default
`--format <format>`	OpenAI: `png`, `jpeg`, `webp`	`png`
`--compression <0-100>`	OpenAI jpeg/webp compression	provider default
`--background <mode>`	OpenAI: `transparent`, `opaque`, `auto`	provider default
`-o, --output <path>`	Output directory	system temp directory
`--sync`	Wait for the provider before returning	off
`--send`	Send to the current chat	off (on in a chat session)
`--caption <text>`	Caption when sending	the prompt
`--execute`	Confirm delivery to a chat	off (dry-run)
`--json`	Print the JSON result	off

Video analysis

ravi video analyze turns a YouTube URL or a local video into a Markdown file. With the default strategy (auto), YouTube videos use their subtitles through yt-dlp and fall back to Gemini when there are none. Local files always use Gemini.

ravi video analyze "https://www.youtube.com/watch?v=VIDEO_ID"
ravi video analyze "https://www.youtube.com/watch?v=VIDEO_ID" -o ./analysis.md
ravi video analyze "https://www.youtube.com/watch?v=VIDEO_ID" -p "Focus on the technical arguments"
ravi video analyze "https://www.youtube.com/watch?v=VIDEO_ID" --strategy subtitles   # fail if no subtitles
ravi video analyze "https://www.youtube.com/watch?v=VIDEO_ID" --force-analyze       # always use Gemini
ravi video analyze ./demo.mp4

Flag	Description	Default
`--strategy <strategy>`	`auto`, `subtitles` or `gemini`	`auto`
`--force-analyze`	Same as `--strategy gemini`	off
`-p, --prompt <text>`	Custom prompt for Gemini	built-in prompt
`-o, --output <path>`	Output file	a new `.md` file in the current directory
`--json`	Print the JSON result	off

The Gemini model is gemini-2.5-flash unless you set GEMINI_VIDEO_MODEL. The subtitles path does not need GEMINI_API_KEY. Local files (.mp4, .mpeg, .mpg, .mov, .avi, .flv, .webm, .wmv, .3gpp) are uploaded to the Gemini Files API. YouTube videos must be public. The Markdown file has the title, duration, strategy, transcript and chapters. When Gemini is used it also has a summary, topics and timestamped visual descriptions.

Send any file

ravi media send delivers an image, video, audio file or document and waits for the channel to accept it.

# From an agent session: back to the current chat
ravi media send ./report.pdf --caption "Weekly report" --execute

# WhatsApp from your terminal: instance name and chat ID
ravi media send ./photo.jpg --account wa-main --to "[email protected]" --execute

# WhatsApp voice note
ravi media send ./note.ogg --account wa-main --to "[email protected]" --ptt --execute

# Slack from your terminal: --channel slack is required, plus the channel config name and Slack channel ID
ravi media send ./chart.png --channel slack --account slack-main --to C0123456789 --execute

# Slack thread
ravi media send ./chart.png --channel slack --account slack-main --to C0123456789 \
  --thread-id 1760013000.123456 --execute

Flag	Description
`--caption <text>`	Caption or message text
`--to <chatId>`	Target chat: a WhatsApp JID (`[email protected]`, `[email protected]`) or a Slack channel ID
`--account <id>`	Instance (WhatsApp) or Slack channel config name
`--channel <channel>`	Channel. Pass `slack` to deliver through Slack; otherwise Omni is used
`--thread-id <id>`	Thread or topic, for channels that have them
`--ptt`	Send audio as a voice note (WhatsApp)
`--execute`	Actually send. Without it: dry-run, exit 3
`--json`	Print the JSON result

The type comes from the extension: .jpg, .jpeg, .png, .gif, .webp are images; .mp4, .mov, .avi, .mkv are videos; .mp3, .ogg, .wav, .m4a, .opus are audio; anything else (including .pdf) is sent as a document.

Stickers (WhatsApp)

Ravi keeps a sticker catalog at ~/.ravi/stickers/catalog.json. Only WhatsApp supports outbound stickers today. The agent never sees sticker files; when stickers are enabled for it, its prompt gets a short list of sticker IDs and when to use them.

ravi stickers add wave ./wave.webp \
  --label "Wave" \
  --description "Use for a friendly quick hello." \
  --avoid "Do not use during serious incidents."

ravi stickers list
ravi stickers show wave
ravi stickers remove wave --execute

# From a WhatsApp session, to the current chat
ravi stickers send wave --execute

# Explicit target
ravi stickers send wave --channel whatsapp --account wa-main --to "[email protected]" --execute

stickers add also takes --channels <csv> (default whatsapp), --agents <csv> (default: all agents), --disabled and --overwrite. stickers send and stickers remove are dry-runs without --execute. Sending queues the sticker for the daemon to deliver. Stickers are opt-in per agent: set "stickers": {"enabled": true} in the agent defaults (next section).

Agent, instance and global defaults

Instead of passing flags every time, store defaults:

Where	Keys	Command
Agent	`tts_voice`, `tts_model`, `tts_speed`, `tts_lang`, `image_provider`, `image_model`, `image_mode`, `image_aspect`, `image_size`, `image_quality`, `image_format`, `image_compression`, `image_background`, `stickers`	`ravi agents set <agent> defaults '<json>'`
Instance	the `image_*` keys	`ravi instances set <instance> defaults '<json>'`
Global	`image.provider`, `image.model`, `image.mode`, `image.quality`, `image.format`	`ravi settings set <key> <value>`

ravi settings set image.provider openai
ravi instances set wa-main defaults '{"image_provider":"openai","image_model":"gpt-image-2","image_format":"png"}'

defaults replaces the whole JSON object, and the agent’s defaults also hold its runtime permissions (runtimePermissions). Writing ravi agents set main defaults '{"tts_lang":"en"}' would drop the agent’s permission profile. Read the current object first and write back the merged version:

ravi agents show main --json | jq -c '.agent.defaults + {"tts_lang":"en","stickers":{"enabled":true}}'
ravi agents set main defaults '<paste the JSON printed above>'
ravi agents permissions main    # confirm the profile is still there

Files people send to your agent

When a message with a file arrives on Slack or WhatsApp, Ravi downloads it into the agent’s working directory and puts the local path in the prompt, so the agent can open it with its tools.

Location: <agent cwd>/attachments/, for example ~/ravi/main/attachments/.
Name: {timestamp}-{messageId}.{ext}.
Size limit: 20 MB. A larger file, or one that fails to download, still appears in the prompt, but without a file path.
Audio: saved and transcribed (see Transcription).

The message body the agent sees for a WhatsApp image with a caption, and for a voice note:

[Image: /home/you/ravi/main/attachments/1760013000000-3EB0C4A1B2.jpg]
Look at this

[Audio]
Transcript:
Can you send me the report?
file: /home/you/ravi/main/attachments/1760013000000-3EB0C4A1B3.ogg

The message body for Slack files:

[Attachment: report.pdf, application/pdf, 1.2 MB]
file: /home/you/ravi/main/attachments/1760013000512-1760013000_123456-F0123456789.pdf

[Audio: voice-note.m4a, audio/mp4, 220.4 KB]
Transcript:
Can you send me the report?
file: /home/you/ravi/main/attachments/1760013000731-1760013000_123456-F0123456790.m4a

Artifacts: every generated image is recorded there.
Skills: the first ravi audio, ravi image, ravi video or ravi stickers call in an agent session loads the matching skill.
Connect Slack and Connect WhatsApp: the channels media is delivered to.
Configuration: everything ~/.ravi/.env can hold.

​Before you start

​Audio generation (text to speech)

​Transcription

​Voice messages your agent receives

​Image generation

​Choose a provider first

​Generate

​Video analysis

​Send any file

​Stickers (WhatsApp)

​Agent, instance and global defaults

​Files people send to your agent

​Related

Before you start

Audio generation (text to speech)

Transcription

Voice messages your agent receives

Image generation

Choose a provider first

Generate

Video analysis

Send any file

Stickers (WhatsApp)

Agent, instance and global defaults

Files people send to your agent

Related