Dagu FFmpeg Action

Official Dagu action for running ffmpeg and ffprobe with a pinned FFmpeg binary.

This action keeps FFmpeg out of the Dagu core binary while still giving workflows a portable, versioned media-processing step. The action pins Tyrrrz/FFmpegBin@8.1 with Dagu tools, which uses aqua internally.

Usage

type: graph

steps:
  - id: convert
    action: ffmpeg@v1
    with:
      overwrite: true
      args: >-
        -i input.mov -c:v libx264 -c:a aac output.mp4

args is the FFmpeg argument string excluding the executable name. It is parsed into argv by the action wrapper, not by a shell. Quote paths or filter expressions that contain spaces.

For exact argument boundaries, pass a JSON array string:

args: '["-i","input.mov","-c:v","libx264","-c:a","aac","output.mp4"]'

The action runs ffmpeg by default and prepends automation-safe options:

• -hide_banner unless hideBanner: false
• -nostdin unless nostdin: false
• -n by default, or -y when overwrite: true

FFmpeg options are order-sensitive. Put input options before the related -i, and output options before the output path.

Write Outputs as Artifacts

Use DAG_RUN_ARTIFACTS_DIR for files that should be retained with the DAG run:

type: graph

steps:
  - id: make_clip
    action: ffmpeg@v1
    with:
      overwrite: true
      args: >-
        -f lavfi -i testsrc=size=1280x720:rate=30:duration=5 -pix_fmt yuv420p "${DAG_RUN_ARTIFACTS_DIR}/clips/testsrc.mp4"

This keeps media files out of Dagu output variables and makes them available in the run's Artifacts tab.

Probe Media

Set command: ffprobe to inspect a media file. ffprobe stdout is captured in the action output:

steps:
  - id: inspect
    action: ffmpeg@v1
    with:
      command: ffprobe
      args: >-
        -v error -print_format json -show_format -show_streams "${DAG_RUN_ARTIFACTS_DIR}/clips/testsrc.mp4"

  - id: print_probe
    depends: [inspect]
    run: printf '%s\n' '${inspect.outputs.stdout}'

For structured downstream processing, pass ${inspect.outputs.stdout} to a JSON-aware step such as jq.filter or data.pick.

Multiple Inputs and Filters

Use normal FFmpeg argument ordering for multiple inputs, maps, codecs, and filters:

steps:
  - id: overlay
    action: ffmpeg@v1
    with:
      overwrite: true
      args: >-
        -i video.mp4 -i watermark.png -filter_complex overlay=W-w-24:H-h-24 -c:a copy "${DAG_RUN_ARTIFACTS_DIR}/clips/watermarked.mp4"

Working Directory and Environment

Use workdir when paths should resolve relative to a directory, and env for extra process environment variables. env is a newline-delimited KEY=value string:

steps:
  - id: convert
    action: ffmpeg@v1
    with:
      workdir: /data/media
      env: |
        FFREPORT=file=/tmp/ffmpeg-report.log:level=32
      overwrite: true
      args: >-
        -i source.mov "${DAG_RUN_ARTIFACTS_DIR}/converted/source.mp4"

For exact environment values, pass a JSON object string:

env: '{"FFREPORT":"file=/tmp/ffmpeg-report.log:level=32"}'

Captured Outputs

The action captures command stdout and stderr up to maxOutputBytes and publishes a small structured result:

Field	Description
ok	true when the command exits with status 0 before timeout.
exitCode	Process exit code, or -1 when the process was terminated before producing one.
signal	Signal name when the process was terminated by a signal.
command	ffmpeg or ffprobe.
args	Final argument list passed to the command, including action-managed defaults.
stdout	Captured stdout, truncated to maxOutputBytes.
stderr	Captured stderr, truncated to maxOutputBytes.
durationMs	Wrapper-measured command duration in milliseconds.
timedOut	true when timeoutSeconds was reached.
truncated	Object with stdout and stderr booleans.
error	Error object when validation or process startup fails.

Do not use action outputs to carry large media data. Write media to files under DAG_RUN_ARTIFACTS_DIR, a shared mounted path, or object storage.

Inputs

Name	Type	Required	Default	Description
args	string	Yes	-	Shell-style arguments passed to ffmpeg or ffprobe, excluding the executable name. JSON array strings are also accepted.
command	string	No	ffmpeg	Command to run: ffmpeg or ffprobe.
workdir	string	No	action workspace	Working directory for the command.
env	string	No	empty	Extra environment variables as newline-delimited KEY=value entries. JSON object strings are also accepted.
timeoutSeconds	integer	No	3600	Command timeout in seconds.
overwrite	boolean	No	false	For ffmpeg, pass -y when true; otherwise pass -n.
hideBanner	boolean	No	true	Pass -hide_banner.
nostdin	boolean	No	true	For ffmpeg, pass -nostdin.
maxOutputBytes	integer	No	1048576	Maximum bytes captured from stdout and stderr.

Direct CLI Use

If a workflow needs to stream FFmpeg stdout directly to an artifact, use Dagu tools and a command step instead of this action:

tools:
  - Tyrrrz/FFmpegBin@8.1

steps:
  - id: extract_audio
    run: |
      ffmpeg -hide_banner -nostdin -y -i input.mp4 -vn -f wav pipe:1
    stdout:
      artifact: audio/extracted.wav

This avoids putting binary stdout into action output fields.

Local Development

Use source: to call a local checkout:

steps:
  - id: convert
    action: source:file:///path/to/ffmpeg@local
    with:
      overwrite: true
      args: >-
        -f lavfi -i sine=frequency=440:duration=1 "${DAG_RUN_ARTIFACTS_DIR}/tone.wav"

Remote actions run in their own action workspace. If media inputs live in the caller workspace or on shared storage, pass paths that exist on the worker running the action.

References

• FFmpeg command syntax and option ordering: https://ffmpeg.org/ffmpeg.html
• ffprobe JSON output format: https://ffmpeg.org/ffprobe.html
• Aqua standard registry package: https://github.com/aquaproj/aqua-registry/tree/main/pkgs/Tyrrrz/FFmpegBin