A command line tool `scrscr` and a library that decorates screenshots with nice backgrounds and captions.

What's New



This release adds more features like color gradients, colored borders, background images, a new screenshot-only layout and JPEG support.


  • Use linear and radial color gradients, instead of solid colors only. Can be used for "background-color" and "screenshot-border-color". See README for more details about color and gradient definition syntax.
  • Use an image file as background by using the new options "background-image", "background-image-scaling" and "background-image-alignment".
  • Draw a colored border around the screenshot by using the new options "screenshot-border-size" and "screenshot-border-color".
  • New layout type "screenshot-only" that enables to render a screenshot without a caption. The screenshot is centered inside the original image at the desired size factor and may be decorated with a background, border and shadow as usual.
  • Support screenshots in JPEG format, additionally to PNG. Note that the output is still always in PNG format.


  • The caption parameter is now optional, in order to support the "screenshot-only" layout. This enables to use the other layouts without a caption, too. Note that the caption area is still reserved unless the "caption-size-factor" is reduced accordingly.
  • Replaced install.sh file with a Makefile, now supporting install, uninstall, build and clean commands.

ScreenshotScribbler (scrscr)

A command line tool scrscr and a library that creates a new image with same dimensions as a given screenshot, adds a background, reduces the size of the original screenshot, places it nicely and scribbles a caption next to it.


Install with make

There is a Makefile defined for this project. Clone the repository, change into the folder, then execute following to install the scrscr command to your /usr/local/bin folder:

$ make clean install

You can also uninstall by calling:

$ make uninstall

Build and install manually

Clone the repository, change into the folder, then execute:

$ swift build --configuration release
$ cp -f .build/release/scrscr /usr/local/bin/scrscr

Note: Using make is recommended.


By default, the tool places the caption on top and the screenshot on bottom of the image. It uses a white background, black caption and a subtle shadow behind the screenshot.

Following example uses the default settings:

$ scrscr --caption "Scribble this caption" --screenshot example-input.png --output example-output.png

The layout may be customized by using several command line options. The --help describes all options:

$ scrscr --help

Following example defines all possible options including their default values:

$ scrscr \
    --caption "Example output with default options and long caption" \
    --screenshot example-input.png \
    --output example-output-default.png \
    --layout "caption-before-screenshot" \
    --background-color "#FFFFFF" \
    --caption-size-factor 0.25 \
    --caption-alignment "center" \
    --caption-color "#000000" \
    --caption-font-name "SF Compact" \
    --caption-font-style "Bold" \
    --caption-font-size 32 \
    --screenshot-size-factor 0.85 \
    --screenshot-corner-radius 5 \
    --screenshot-shadow-size 5 \
    --screenshot-shadow-color "#000000" \
    --screenshot-border-size 0 \
    --screenshot-border-color "#000000" \

Please also have a look at the examples.sh script and Examples folder for more usage scenarios.

Layout types

There are four different layout types available, which can be defined using the --layout option:

  • caption-before-screenshot (default)
  • caption-after-screenshot
  • caption-between-screenshots
  • screenshot-only

All layouts can be customized further, i.e. the options --caption-size-factor and --screenshot-size-factor enable more variations.

Examples of the four different layout types:

Layout: caption-before-screenshot   Layout: caption-after-screenshot   Layout: caption-between-screenshots   Layout: screenshot-only

Colors and gradients

Defining colors on the command line is inspired by a subset of the widely known CSS syntax.

A single color may be defined in hexadecimal syntax as follows, where each two digits define the red, green and blue part of the color:

--background-color "#0099FF"

Some options also support gradients, i.e. the --background-color and --screenshot-border-color. For gradients, at least two colors have to be defined. The colors are rendered from top to bottom.

Linear gradients:

--background-color "linear-gradient(#FF0000, #FFA500, #FFFF00, #00FF00, #0000FF, #FF00FF)"

Radial gradients:

--background-color "radial-gradient(#FF0000, #0000FF)"

More specialized backgrounds are possible by defining a background image that is rendered behind the screenshot, for example with following options:

--background-image Examples/example-background.jpg
--background-image-scaling "aspect-fill"
--background-image-alignment "bottom"    

Examples of background gradients and images:

Background: linear-gradient   Background: radial-gradient   Background: background-image


I started developing this tool as a side project, because I did not want to use fastlane for any reason, which provides something similar with its frameit plugin. I wanted to have a simple command line tool, which I just can call in my scripts (that already generate screenshots automatically) in order to beautify them for the App Store.

This project uses pure CoreGraphics and CoreText APIs for layouting (no AppKit or UIKit), so it should be quite portable.

There will be updates and new features from time to time and I try to keep working on it, as long as I use it myself.


If you like this tool, you could buy me a coffee :)

Buy Me A Coffee


  • Swift Tools 5.7.0
View More Packages from this Author


Last updated: Thu Jan 19 2023 22:16:59 GMT-0500 (GMT-05:00)