ffcast.1.pod

NAME

ffcast - run command on rectangular screen regions

SYNOPSIS

ffcast [ <options> ] [ { <sub-command> | <command> } [ <args> ] ]

DESCRIPTION

ffcast is a thin glue between interactive screen region selection and command line tools that accept numerical geometry parameters. It makes passing geometry parameters to such tools as easy as a mouse click.

Typically, ffcast prompts the user to select a screen region and injects its geometry parameters into the arguments of <command>, and then executes the resultant command line. This injection is done via format string substitution. See FORMAT STRINGS.

Multiple screen regions can be selected, and are by default combined by "union" into a single region. If no valid region is specified by the user, the root window is selected.

For convenience, ffcast recognizes certain predefined sub-commands, which are looked up before all external commands. It's possible to add or override sub-commands via user configuration. See SUB-COMMANDS.

If neither <sub-command> nor <command> is given, the geometry of the selection is printed.

OPTIONS

Any of the <options> can be repeated. They are parsed and applied in the order they are specified.

-# <n>

Select window with ID <n>.

-b

Include borders of windows to be selected.

-f

Include window manager frame of windows to be selected. The window manager must support _NET_FRAME_EXTENTS.

-g <geospec>

Specify a selection in <geospec>. See GEOMETRY SPECIFICATION.

-h

Print help message, then exit.

-i

Combine selected regions by intersection instead of union.

-q

Be less verbose.

-s

Select a rectangular region by dragging the mouse.

-v

Be more verbose. -v turns on verbose messages. -vv turns on debug.

-w

Select a window by clicking the mouse in that window.

-x <n>

Select a Xinerama head of ID <n>. Multiple heads can be specified either as a comma-separated list, or by repeating this option. Use list or l to get a list of head IDs and the corresponding geometry parameters.

FORMAT STRINGS

The following format strings are supported for all external commands, as well as the sub-commands png and rec:

%D

DISPLAY

%h

Height

%w

Width

%x

Left offset

%y

Top offset

%X

Right offset

%Y

Bottom offset

%c

Equivalent to %x,%y

%C

Equivalent to %X,%Y

%g

Equivalent to %wx%h+%x+%y

%s

Equivalent to %wx%h

The each sub-command supports the following format strings:

%i

The identifier of the selection

%n

This being the nth selection

%t

The type of the selection

The format string %% is always substituted with a literal %, whenever format string substitution is performed. Therefore, multiple levels of escaping may be required when sub-commands are chained.

GEOMETRY SPECIFICATION

A <geospec> specifies a geometry in one of the following forms:

x,y X,Y

x, y, X and Y are the left, top, right and bottom offsets, respectively.

wxh+x+y

w, h, x and y are the width, height, left offset and top offset, respectively.

SUB-COMMANDS

The first normal argument is first looked up in the list of sub-commands. If there is no match, it is executed as an external command.

To bypass sub-command lookup entirely, use % command.

To get a list of all sub-commands, use help without an argument. help sub-command prints help for the specified sub-command.

To import sub-commands, ffcast sources the files @pkglibexecdir@/subcmd, @sysconfdir@/@PACKAGE@/subcmd and $XDG_CONFIG_HOME/@PACKAGE@/subcmd, in that order.

To learn how to register a sub-command, refer to @pkglibexecdir@/subcmd.

EXAMPLES

List all sub-commands with brief description:

ffcast help

Use the sub-command png to take a screenshot of a window, including its window manager frame. Note the png sub-command supports format string substitution:

ffcast -fw png screenshot-%s.png

The -f option works only if the window manager supports _NET_FRAME_EXTENTS. A workaround is to use the pad sub-command to explicitly pad the region with the size of the frame:

ffcast -w pad '20 2 2' png screenshot-%s.png

Roughly select a region, take a screenshot sans the edges:

ffcast -s trim png screenshot-%s.png

The pad sub-command allows arithmetic operations on the region geometry parameters (w, h, x, y, X, Y, rw, rh):

ffcast -s trim pad 'w>400?10:5' png

To take a screenshot of the active window quickly, bind the following to a keyboard shortcut:

ffcast -q -# "$(xdotool getactivewindow)" png /tmp/"$(date +%F\ %T)".png

Use the sub-command rec to record a fullscreen screencast on display :1. The rec sub-command accepts the -m option, which crops the video so both its width and height are divisible by the given number:

DISPLAY=:1 ffcast -vv rec -m 4 screencast.mkv

Record a screencast of all three windows of GIMP combined. This works because all selections are by default combined by union. Note format strings are always substituted for external commands:

ffcast -www ffmpeg -f x11grab -show_region 1 -s %s -i %D+%c gimp.mp4

Keep selecting either regions (mouse drag) or windows (mouse click) until key press, then start recording the combined region of these selections:

ffcast -q $(while slop -q -n -f '-g %g ';do :;done) rec /tmp/rec-%s.mp4

End the most recently started screencast session (hint: keyboard shortcuts):

pkill -fxn '(/\S+)*ffmpeg\s.*\sx11grab\s.*'

Take a screenshot of two windows combined, excluding anything invisible on head 0:

ffcast -ww ffcast -i -x 0 -g %g png

Take three individual screenshots of heads 0, 1, 2, one by one. The each command runs a command for each user selection consecutively; it supports several format strings:

ffcast -x 0,1,2 each png %t_%i-%s.png

Similarly, in a tiling WM, take a screenshot of each xterm window in view:

ffcast $(xdotool search --onlyvisible --class '^XTerm$'|sed i-#) each png

To do the same thing, but in parallel, and with padding:

xdotool search --onlyvisible --class '^XTerm$' |
xargs -P0 -I+ ffcast -# + -qq pad '20 2 2' png -y /tmp/+.png

Resize a floating window to the same size as another, by two mouse clicks:

ffcast -w xdotool selectwindow windowsize %w %h windowactivate

SEE ALSO

ffmpeg(1), X(7)

REPORTING BUGS

Send bug reports and feature requests to <@PACKAGE_BUGREPORT@>.

AUTHOR

lolilolicon <[email protected]>