MENYOKI(1)

NAME
menyoki - screenshot/screencast and perform image operations on the command line

SYNOPSIS
menyoki [FLAGS] [OPTIONS] <SUBCOMMAND>

DESCRIPTION

menyoki is a screencast and screenshot utility that can also perform various image related operations such as making/splitting GIFs and modifying/analyzing/viewing image files. It aims to be a lightweight command line tool for either helping out on day-to-day life operations or complicated detail-centric issues. Originally it was designed to record/screenshot terminal windows but it can be tweaked easily for other purposes with command line arguments, environment variables, or a configuration file.

USAGE

Command line arguments of menyoki are designed to be as intuitive as possible. As a result of that, an action can be performed with a chain of subcommands along with the flags and options. The general prototype for the usage of command line arguments is the following:

menyoki (ACTION) (FORMAT) (OUTPUT)

The subcommand that will indicate the action is mandatory whereas format and output subcommands might be optional (or they might not exist at all). The format subcommand can be one of the supported formats and output basically corresponds to the save subcommand.

The default format is the first listed subcommand if there is not any subcommand given for specifying a format. On the other hand, save subcommand uses the “menyoki” directory in the home (or images if it exists) as the default output directory.

GENERAL ARGUMENTS

Flags and options that will generally affect the execution of menyoki can be set before specifying the main action to perform. Then the main subcommand (action) must be specified.

menyoki [FLAGS] [OPTIONS] <SUBCOMMAND>

  Arguments

    FLAGS:
        -h, --help       Print help information
        -V, --version    Print version information
        -v, --verbose    Increase logging verbosity
        -q, --quiet      Do not show output
    OPTIONS:
        -c, --config <FILE>    Set the configuration file
            --color <HEX>      Set the main color [default: 3AA431]
    SUBCOMMANDS:
        record     Record an animation
        split      Split an animation into frames
        make       Make an animation from frames
        capture    Capture an image
        edit       Edit an image
        analyze    Analyze an image
        view       View an image

  Examples

Command | Action
menyoki -V | Print the version information
menyoki -vv --color FF00FF <action> | Set log verbosity level to 2 (trace) and use “FF00FF” as the main color
menyoki -q -c menyoki.conf <action> | Run in quiet mode and read the configuration from “menyoki.conf”

RECORD SUBCOMMAND

menyoki can record an area of a window or the whole screen and encode it as a supported format. Area selection and resize is performed with the key bindings.

A few scenarios that record action might be helpful would be:

•   Record a specific area of a window

•   Record for a given duration

•   Record the output of a command (especially for TUI applications)

Encoding options can be changed using the arguments of the provided format. (See the output of menyoki record gif --help)

menyoki record [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

  Arguments

    FLAGS:
        -r, --root          Record the root window
        -f, --focus         Record the focused window
            --select        Select the window to record
            --parent        Record the parent of the window
            --with-alpha    Record with the alpha channel
            --no-keys       Disable the action keys while recording
        -m, --mouse         Select the window with mouse click
        -h, --help          Print help information
    OPTIONS:
            --action-keys <KEYS>    Set the action keys [default: LAlt-S,LAlt-Enter]
            --cancel-keys <KEYS>    Set the cancel keys [default: LControl-D,Escape]
        -b, --border <BORDER>       Set the border width [default: 1]
        -p, --padding <T:R:B:L>     Set the record area padding
        -s, --size <WxH>            Set the record area size
        -d, --duration <S>          Set the duration for recording [default: ∞]
        -c, --countdown <S>         Set the countdown before recording [default: 3]
        -t, --timeout <S>           Set the timeout for window selection [default: 300]
        -i, --interval <MS>         Set the refresh interval for window selection [default: 10]
            --font <FONT>           Set the font to use for window selection
            --monitor <NUM>         Set the monitor to record as root window
    ARGS:
        <COMMAND>    Set the command to run
    SUBCOMMANDS:
        gif     Use the GIF encoder
        apng    Use the APNG encoder
        save    Save the output file(s)

  Examples

Command | Action
menyoki record | Select a window and start recording with default settings
menyoki record --root --countdown 5 | Record the root window after 5 seconds of countdown
menyoki record --focus --with-alpha | Record the focused window with the alpha channel (for transparency)
menyoki record --size 200x300 --duration 10 | Record an area of size 200x300 for 10 seconds
menyoki record --padding 20:10:0:10 --timeout 120 | Record an area with given padding and set window selection timeout to 120 seconds
menyoki record --parent | Record the parent window of the selected window
menyoki record --root --select --monitor 1 | Record the first monitor as root window
menyoki record --border 5 | Record the area selected by a border with 5 width
menyoki record --action-keys LControl-Q,LAlt-W | Record with the default settings using custom key bindings
menyoki record --cancel-keys LControl-X,E | Record with the default settings using custom key bindings
menyoki record gif --fps 15 --quality 90 | Record 15 frames per second with 90% quality
menyoki record gif --gifski | Record and encode using the gifski encoder
menyoki record gif save "test.gif" --timestamp | Record and save as “test.gif” with timestamp in the file name
menyoki record apng --fps 30 | Record 30 frames per second and encode as APNG
menyoki -q record save "-" > test.gif | Record and redirect output to “test.gif”
menyoki -q record "kmon -t 2000" | Execute the command and record its output in quiet mode
menyoki record --font "-*-dejavu sans-*-*-*-*-17-*-*-*-*-*-*-*" | Use custom font for showing the area size (see xfontsel)

SPLIT SUBCOMMAND

menyoki can split an animation into frames (extract images) if the split subcommand is provided and it can save frames as one of the supported formats with the use of trailing format subcommand.

menyoki split [OPTIONS] <FILE> [SUBCOMMAND]

  Arguments

    FLAGS:
        -h, --help    Print help information
    OPTIONS:
        -d, --dir <DIRECTORY>    Set the output directory
    ARGS:
        <FILE>    Set the animation file
    SUBCOMMANDS:
        png     Use the PNG encoder
        jpg     Use the JPG encoder
        webp    Use the WebP encoder
        bmp     Use the BMP encoder
        ico     Use the ICO encoder
        tiff    Use the TIFF encoder
        tga     Use the TGA encoder
        pnm     Use the PNM encoder
        ff      Use the farbfeld encoder
        exr     Use the OpenEXR encoder

  Examples

Command | Action
menyoki split rec.gif | Extract frames from the “rec.gif” file
menyoki split rec.gif jpg --quality 100 | Extract frames as JPEG in maximum quality
menyoki split rec.gif --dir frames/ | Extract frames and save them to the specified directory

MAKE SUBCOMMAND

make subcommand serves the purpose of creating an animation from a set of images. For example, it can be used for making GIFs from given images either via the command line or the specified directory.

menyoki make [FLAGS] [OPTIONS] <FRAMES>... [SUBCOMMAND]

  Arguments

    FLAGS:
            --gifski     Use the gifski encoder
            --fast       Encode 3 times faster (gifski)
        -n, --no-sort    Use frames in the order given
        -h, --help       Print help information
    OPTIONS:
        -f, --fps <FPS>            Set the FPS [default: 20]
        -q, --quality <QUALITY>    Set the frame quality (1-100) [default: 75]
        -r, --repeat <REPEAT>      Set the number of repetitions [default: ∞]
        -d, --dir <DIRECTORY>      Set the directory to read frames
            --format <FORMAT>      Set the animation format [default: gif]  [possible values: gif, apng]
    ARGS:
        <FRAMES>...    Set the animation frames
    SUBCOMMANDS:
        save    Save the output file(s)

  Examples

Command | Action
menyoki make 1.png 2.png | Make a GIF that consists of two frames as “1.png” and “2.png”
menyoki make 1.png 2.png --fps 5 --quality 100 | Make a GIF with the specified properties from given frames
menyoki make 1.png 2.png save 3.gif --date | Make a GIF and save the file (“3.gif”) with the date information
menyoki make 1.png 2.png --format apng | Make an APNG from the given frames
menyoki make --dir frames/ | Make a GIF from the frames in the specified directory

CAPTURE SUBCOMMAND

menyoki can capture (screenshot) an area of a window or the whole screen and encode it as a supported format. Formats like png, jpg, and pnm have their own flags and options that might be used for changing the default encoding settings. Similar to the record subcommand, area selection and resize is performed with the key bindings. The same flags and options might apply for both record and capture subcommands since the actions are abstractly alike.

menyoki capture [FLAGS] [OPTIONS] [COMMAND] [SUBCOMMAND]

  Arguments

    FLAGS:
        -r, --root          Capture the root window
        -f, --focus         Capture the focused window
            --select        Select the window to capture
            --parent        Record the parent of the window
            --with-alpha    Capture with the alpha channel
        -m, --mouse         Select the window with mouse click
        -h, --help          Print help information
    OPTIONS:
            --action-keys <KEYS>    Set the action keys [default: LAlt-S,LAlt-Enter]
            --cancel-keys <KEYS>    Set the cancel keys [default: LControl-D,Escape]
        -b, --border <BORDER>       Set the border width [default: 1]
        -p, --padding <T:R:B:L>     Set the capture area padding
        -s, --size <WxH>            Set the capture area size
        -c, --countdown <S>         Set the countdown before capturing [default: 0]
        -t, --timeout <S>           Set the timeout for window selection [default: 300]
        -i, --interval <MS>         Set the refresh interval for window selection [default: 10]
            --font <FONT>           Set the font to use for window selection
            --monitor <NUM>         Set the monitor to capture as root window
    ARGS:
        <COMMAND>    Set the command to run
    SUBCOMMANDS:
        png     Use the PNG encoder
        jpg     Use the JPG encoder
        webp    Use the WebP encoder
        bmp     Use the BMP encoder
        ico     Use the ICO encoder
        tiff    Use the TIFF encoder
        tga     Use the TGA encoder
        pnm     Use the PNM encoder
        ff      Use the farbfeld encoder
        exr     Use the OpenEXR encoder
        save    Save the output file(s)

  Examples

Command | Action
menyoki capture | Select a window and screenshot with default settings
menyoki capture --root --countdown 5 | Screenshot the root window after 5 seconds of countdown
menyoki capture --focus --with-alpha | Screenshot the focused window with the alpha channel (for transparency)
menyoki capture --size 200x300 --duration 10 | Screenshot an area of size 200x300 for 10 seconds
menyoki capture --padding 20:10:0:10 --timeout 120 | Screenshot an area with given padding and set window selection timeout to 120 seconds
menyoki capture png --filter avg --compression fast | Screenshot and encode with the specified PNG options
menyoki capture jpg --quality 100 | Screenshot and encode with the specified JPEG options
menyoki capture webp --lossless | Screenshot and encode with the specified WEBP options
menyoki capture pnm --format pixmap --encoding ascii | Screenshot and encode with the specified PNM options
menyoki capture ff save "test.ff" --timestamp | Screenshot and save as “test.ff” in farbfeld format with timestamp in the file name
menyoki -q capture png save "-" > test.png | Screenshot and redirect output to “test.png”
menyoki -q capture "kmon -t 2000" | Execute the command and screenshot its output in quiet mode (sets countdown to 3 implicitly)

EDIT SUBCOMMAND

edit subcommand can be used to edit (https://github.com/image-rs/image#image-processing-functions) (manipulate/filter/convert) files in one of the supported formats. Apart from the flags and options that edit provides, other encoding options can be specified via format subcommand.

menyoki edit [FLAGS] [OPTIONS] <FILE> [SUBCOMMAND]

  Arguments

    FLAGS:
            --convert      Convert image using the given encoder
            --grayscale    Convert image to grayscale
            --invert       Invert the colors of the image
        -h, --help         Print help information
    OPTIONS:
            --crop <T:R:B:L>             Apply padding to crop the image
            --resize <WxH>               Resize the image without keeping the aspect ratio
            --ratio <RATIO>              Resize the image proportionally by aspect ratio [default: 1.0]
            --rotate <ROTATE>            Rotate the image (clockwise) [possible values: 90, 180, 270]
            --flip <FLIP>                Flip the image [possible values: horizontal, vertical]
            --blur <SIGMA>               Blur the image [default: 0.0]
            --hue <HUE>                  Adjust the hue of the image [default: 0]
            --contrast <CONTRAST>        Adjust the contrast of the image [default: 0.0]
            --brightness <BRIGHTNESS>    Adjust the brightness of the image [default: 0]
            --filter <FILTER>            Set the sampling filter for scaling [default: lanczos3]  [possible values: nearest, triangle, catmull-rom, gaussian,
                                         lanczos3]
    ARGS:
        <FILE>    Set the input file
    SUBCOMMANDS:
        gif     Use the GIF encoder
        apng    Use the APNG encoder
        png     Use the PNG encoder
        jpg     Use the JPG encoder
        webp    Use the WebP encoder
        bmp     Use the BMP encoder
        ico     Use the ICO encoder
        tiff    Use the TIFF encoder
        tga     Use the TGA encoder
        pnm     Use the PNM encoder
        ff      Use the farbfeld encoder
        exr     Use the OpenEXR encoder
        save    Save the output file(s)

  Examples

Command | Action
menyoki edit test.png | Re-encode the “test.png” file without editing
menyoki edit test.png --grayscale | Convert image to grayscale
menyoki edit test.png --invert | Invert the colors of the image
menyoki edit test.png --crop 20:20:20:20 | Apply the given padding to image for cropping
menyoki edit test.png --resize 300x300 | Resize the image to 300x300 (without keeping the aspect ratio)
menyoki edit test.png --ratio 0.5 | Resize the image to half the size (using the aspect ratio)
menyoki edit test.png --ratio 2.0 --filter gaussian | Resize the image using the specified sampling filter
menyoki edit test.png --rotate 90 | Rotate the image 90 degrees (clockwise)
menyoki edit test.png --flip horizontal | Flip the image horizontally
menyoki edit test.png --blur 2.0 | Blur the image
menyoki edit test.png --hue 100 | Adjust the hue of the image
menyoki edit test.png --contrast -10.5 | Adjust the contrast of the image
menyoki edit test.png --brightness 50 | Adjust the brightness of the image
menyoki edit test.png --convert tga | Convert image to TGA format
menyoki edit test.png --convert jpg --quality 80 | Convert image to JPEG in 80% quality
menyoki edit test.gif --ratio 0.25 gif --quality 80 | Resize and re-encode “test.gif”
menyoki edit test.gif gif --speed 0.5 | Slow down the GIF (half the speed)
menyoki edit test.gif gif --cut-beginning 1.0 --cut-end 0.5 | Cut the duration of GIF by seconds
menyoki edit test.apng --convert gif | Convert APNG to GIF
menyoki edit test.ff --grayscale --convert pnm --format arbitrary save "output" --with-extension --date "%H%M%S" | test.ff (farbfeld) -> grayscale -> output_020035.pam (PNM)

ANALYZE SUBCOMMAND

analyze subcommand serves the purpose of inspecting an image file which is in a supported format and creating a report based on the image details. The report consists of 2 to 3 sections that are file, image, and EXIF information.

menyoki analyze [FLAGS] [OPTIONS] <FILE> [SUBCOMMAND]

  Arguments

    FLAGS:
            --timestamp    Use Unix timestamp for report dates
        -h, --help         Print help information
    OPTIONS:
        -t, --time-zone <TIMEZONE>    Set the time zone of the report [default: utc]  [possible values: utc, local]
    ARGS:
        <FILE>    Set the image file
    SUBCOMMANDS:
        save    Save the output file(s)

  Examples

Command | Action
menyoki analyze test.jpg | Inspect “test.jpg” and print the report
menyoki analyze test.jpg save test_report.txt | Inspect “test.jpg” and save the report as “test_report.txt”
menyoki analyze test.jpg --timestamp | Inspect the file and create a report based on timestamps
menyoki analyze test.jpg --time-zone local | Inspect the file and create a report based on local time zone
menyoki analyze test.jpg --timestamp save --timestamp | Use timestamps for both analysis report and file name

VIEW SUBCOMMAND

view subcommand can be used to simply view an image from the terminal. It uses the core library of viu (https://github.com/atanunq/viu).

menyoki view [FLAGS] <FILE>

  Arguments

    FLAGS:
        -t, --transparent    Display transparent image with transparent background
        -h, --help           Print help information
    ARGS:
        <FILE>    Set the input file

  Examples

Command | Action
menyoki view test.jpg | View “test.jpg” from the terminal
menyoki view test.png --transparent | View “test.png” from the terminal with transparency enabled

OTHER SUBCOMMANDS

It’s possible to change the GIF, APNG, PNG, JPG, and PNM encoding options with specifying flags/options to the corresponding subcommands. Also, save subcommand can be used for changing the default output settings.

  GIF/APNG Subcommand

    FLAGS:
            --gifski    Use the gifski encoder         <only in GIF>
            --fast      Encode 3 times faster (gifski) <only in GIF>
        -h, --help    Print help information
    OPTIONS:
        -f, --fps <FPS>            Set the FPS [default: 20]
        -q, --quality <QUALITY>    Set the frame quality (1-100) [default: 75] <only in GIF>
        -r, --repeat <REPEAT>      Set the number of repetitions [default: ∞]
        -s, --speed <SPEED>        Set the GIF speed [default: 1.0]
            --cut-beginning <S>    Cut the beginning of the GIF [default: 0.0]
            --cut-end <S>          Cut the end of the GIF [default: 0.0]
    SUBCOMMANDS:
        save    Save the output file(s)

(Some options might be only usable with a particular action)

  PNG Subcommand

    FLAGS:
        -h, --help    Print help information
    OPTIONS:
        -c, --compression <COMPRESSION>    Set the compression level [default: fast]  [possible values: default, fast, best]
        -f, --filter <FILTER>              Set the filter algorithm [default: sub]  [possible values: none, sub, up, avg, paeth]
    SUBCOMMANDS:
        save    Save the output file(s)

  JPG Subcommand

    FLAGS:
        -h, --help    Print help information
    OPTIONS:
        -q, --quality <QUALITY>    Set the image quality (1-100) [default: 90]
    SUBCOMMANDS:
        save    Save the output file(s)

  WEBP Subcommand

    FLAGS:
        -l, --lossless    Use lossless encoding
        -h, --help        Print help information
    OPTIONS:
        -q, --quality <QUALITY>    Set the lossy encoding quality (1-100) [default: 80]
    SUBCOMMANDS:
        save    Save the output file(s)

  PNM Subcommand

    FLAGS:
        -h, --help    Print help information
    OPTIONS:
        -f, --format <FORMAT>        Set the PNM format [default: pixmap]  [possible values: bitmap, graymap, pixmap, arbitrary]
        -e, --encoding <ENCODING>    Set the encoding for storing the samples [default: binary]  [possible values: binary, ascii]
    SUBCOMMANDS:
        save    Save the output file(s)

  Save Subcommand

    FLAGS:
        -e, --with-extension    Always save the file with an extension
        -t, --timestamp         Add Unix timestamp to the file name
        -h, --help              Print help information
    OPTIONS:
        -d, --date <FORMAT>    Add formatted date/time to the file name [default: %Y%m%dT%H%M%S]
    ARGS:
        <FILE>    Set the output file

KEY BINDINGS

Key bindings are only used and present while capture or record actions are performed. Essentially key bindings are for selecting capture/record areas and resizing them without any mouse interaction.

There are 3 types of key bindings in terms of performed action:

•   Action keys (main action keys such as LAlt-S, can be customized (https://docs.rs/device_query/latest/device_query/keymap/enum.Keycode.html) via --action-keys and --cancel-keys options)

•   Cancel keys (the keys that will cancel the operation, e.g. LControl-D)

•   Miscellaneous keys (the keys that can be used for resizing the selected area such as LAlt-[up])

Key | Action
LAlt-[S/Enter] | Start/stop recording or screenshot the selected area
LControl-D, Escape | Cancel the current operation
LControl-C | Cancel the current operation or stop recording
LAlt-[arrow keys/hjkl] | Increase the area padding (decrease the size of the area)
LControl-LAlt-[arrow keys/hjkl] | Decrease the area padding (increase the size of the area)
LShift-LAlt-[arrow keys/hjkl] | Reposition the selected area (move around)
LAlt-[1-9] | Set the speed factor of changing the area size (default: 3)
LAlt-R | Reset the area padding to default

AUTHOR
Written by Orhun Parmaksız <orhunparmaksiz@gmail.com>

REPORTING BUGS
Contact the author via email or use GitHub Issues for reporting bugs: <https://github.com/orhun/menyoki/issues/>

COPYRIGHT
Copyright © 2020-2023 Orhun Parmaksız
    Licensed under GPLv3: <https://gnu.org/licenses/gpl.html>

SEE ALSO
menyoki.conf(5) See the project homepage at <https://github.com/orhun/menyoki> for full documentation.