=head1 NAME

ffcast - run command on rectangular screen regions

=head1 SYNOPSIS

=over 4

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

=back

=head1 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 the
geometry parameters thereof into the arguments of I<E<lt>commandE<gt>>, and
then executes the resultant command line. This injection is done via format
string substitution. See B<L<FORMAT STRINGS|/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.

ffcast maintains an internal list of predefined B<sub-commands>, which is
looked up before all external commands. It's possible to add or override
sub-commands via user configuration. See B<L<SUB-COMMANDS|/SUB-COMMANDS>>.

If neither I<E<lt>sub-commandE<gt>> nor I<E<lt>commandE<gt>> is given, the
geometry of the selection is printed.

=head1 OPTIONS

Any of the I<E<lt>optionsE<gt>> can be repeated. They are parsed and applied
in the order they are specified.

=over 4

=item B<-#> I<E<lt>nE<gt>>

Select window with ID I<E<lt>nE<gt>>.

=item B<-b>

Include borders of windows to be selected.

=item B<-f>

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

=item B<-g> I<E<lt>geospecE<gt>>

Specify a selection in I<E<lt>geospecE<gt>>.
See B<L<GEOMETRY SPECIFICATION|/GEOMETRY SPECIFICATION>>.

=item B<-h>

Print help message, then exit.

=item B<-i>

Combine selected regions by intersection instead of union.

=item B<-q>

Be less verbose.

=item B<-s>

Select a rectangular region by dragging the mouse.

=item B<-v>

Be more verbose. B<-v> turns on verbose messages. B<-vv> turns on debug.

=item B<-w>

Select a window by clicking the mouse in that window.

=item B<-x> I<E<lt>nE<gt>>

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

=back

=head1 FORMAT STRINGS

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

=over 4

=item B<%D>

B<DISPLAY>

=item B<%h>

Height

=item B<%w>

Width

=item B<%x>

Left offset

=item B<%y>

Top offset

=item B<%X>

Right offset

=item B<%Y>

Bottom offset

=item B<%c>

Equivalent to B<%x,%y>

=item B<%C>

Equivalent to B<%X,%Y>

=item B<%g>

Equivalent to B<%wx%h+%x+%y>

=item B<%s>

Equivalent to B<%wx%h>

=back

The B<each> sub-command supports the following format strings:

=over 4

=item B<%i>

The identifier of the selection

=item B<%n>

This being the I<n>th selection

=item B<%t>

The type of the selection

=back

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

=head1 GEOMETRY SPECIFICATION

A I<E<lt>geospecE<gt>> specifies a geometry in one of the following forms:

=over 4

=item S<I<x>B<,>I<y> I<X>B<,>I<Y>>

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

=item I<w>B<x>I<h>B<+>I<x>B<+>I<y>

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

=back

=head1 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 B<%> I<command>.

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

To import sub-commands, ffcast B<source>s the files I<@pkglibexecdir@/subcmd>,
I<@sysconfdir@/@PACKAGE@/subcmd> and I<$XDG_CONFIG_HOME/@PACKAGE@/subcmd>,
in that order.

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

=head1 EXAMPLES

List all sub-commands with brief description:

    ffcast help

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

    ffcast -fw png screenshot-%s.png

The B<-f> option works only if the window manager supports
B<_NET_FRAME_EXTENTS>. A workaround is to use the B<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 B<pad> sub-command allows arithmetic operations on the region geometry
parameters (C<w>, C<h>, C<x>, C<y>, C<X>, C<Y>, C<rw>, C<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 B<rec> to record a fullscreen screencast on display C<:1>.
The B<rec> sub-command accepts the B<-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 B<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

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 B<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

=head1 SEE ALSO

B<ffmpeg(1)>, B<X(7)>

=head1 REPORTING BUGS

Send bug reports and feature requests to E<lt>B<@PACKAGE_BUGREPORT@>E<gt>.

=head1 AUTHOR

lolilolicon E<lt>lolilolicon@gmail.comE<gt>

=for comment
vim:ft=pod:spell:spelllang=en_us:cc=78:

=cut
