TextOverlay is an application for macOS written with SwiftUI that receives text by command line and shows it as an overlay on the screen, and can be used with any automation applications capable of running Shell Script, such as Shortcuts, Automator, Script Editor, Keyboard Maestro, Alfred, PopClip, and more.
TextOverlay.app/Contents/MacOS/TextOverlay <TEXT> \
[-position {top|bottom|center}[,{left|right|center}]] \
[-textAlign {leading|left|center|trailing|right}] \
[-title <string>] [-titleAlign {leading|left|center|trailing|right}] \
[-icon <SF Symbol name>] [-iconPosition {left|right}] \
[-iconRenderingMode {monochrome|hierarchical|palette|multicolor}] \
[-iconColor <primary>[,<secondary>[,<tertiary>]]] \
[-marginTop <integer>] [-marginBottom <integer>] [-marginLeft <integer>] [-marginRight <integer>] \
[-overlayWidth <integer>] [-autoDismiss <bool>] [-duration <seconds>] \
[-fadeInDuration <seconds>] [-fadeOutDuration <seconds>] \
[-transition {fade|scale|fromTop|fromBottom|fromLeft|fromRight|none}] \
[-colorScheme {system|light|dark|inverted}]
The first parameter is the text of the information to be shown, which may contain one or more lines of text.
Supports the insertion of SF Symbols icons along the text by inserting the placeholder with the following format:
[<SF Symbol name>]
The in-line SF Symbol icon marker is automatically replaced by the symbol whose name is defined between the bracket characters.
You can set a color for a specific text snippet with the following syntax:
<color=<Color name>;<The text to which the color will be applied>>
Standard macOS system color names are supported, such as red, yellow, green and accentColor. It is also possible to define colors using hexadecimal color code.
For example, the text The quick brown <color=brown;fox> jumps over the lazy dog applies the brown color to the word “fox”.
Defines the vertical and horizontal position of the screen where the overlay should be displayed. The values must be separated by comma. The first value indicates the vertical position (options: top, bottom or center), and the second value indicates the horizontal position (options: left, right or center).
For example, to show the overlay at the top and center of the screen, just use the -position "top" parameter.
Defines the text alignment. Options:
leftleading(alias ofleft)centerrighttrailing(alias ofright)
Defines the first line of text that is shown just above the main text. It is automatically formatted in bold. It also supports the insertion of SF Symbols along the text by inserting the marker [<SF Symbol name>] at the desired position.
Allows you to set the alignment of the title independently of the alignment of the main text. The available options are the same as the -textAlign parameter.
Allows you to set an SF Symbol icon to be shown as the main icon on the overlay. The argument is the name of the SF Symbol icon.
Example:
-icon "heart.fill"
Defines the position where icon is shown on the overlay. The options are left or right.
Allows you to set the rendering mode of the colors of the main icon. The options are:
monochromehierarchicalpalettemulticolor
Allows you to set the colors of the main icon shown on the overlay. Up to 3 comma-separated arguments can be passed following the following syntax:
-iconColor <primary>[,<secondary>[,<tertiary>]]
Standard macOS system color names are supported, such as red, yellow, green and accentColor. It is also possible to define colors using hexadecimal color code.
Allows you to define margins that the overlay should have at each end of the screen. The default values in pixels are:
-marginTop(default: 110)-marginBottom(default: 120)-marginLeft(default: 50)-marginRight(default: 50)
By default, the TextOverlay application does not add line breaks to the text that is received by parameter, and the dimensions of the overlay automatically adjust to accommodate the content. This can be a problem when the user has no control over the text that will be displayed. In this case, the -maxWidth parameter limits the width of the overlay and adds line breaks to the text automatically when necessary.
The default behavior of the overlay is to remain visible on the screen until the user clicks on it with the mouse to discard it. To discard the overlay automatically after a predefined period of time, use the -autoDismiss true parameter.
Allows you to set the duration of the time interval in seconds in which the overlay is displayed on the screen until it is automatically discarded. If the duration ends while the mouse pointer is over the overlay, it continues to be shown until the user moves the mouse pointer out of the overlay area. The user can click on the overlay at any time to discard it in advance.
Sets the animation style with which the overlay appears on the screen. The available options are:
fadescalefromTopfromBottomfromLeftfromRightnone
Allows you to set the duration in seconds of the animation with which the overlay appears on the screen.
Allows you to set the duration in seconds of the animation with which the overlay disappears from the screen.
Allows you to set the appearance style of the overlay. The options are:
system(Same appearance of the system)lightdarkinverted(Displays light appearance when the system appearance is set to dark, or dark when the system appearance is set to light)
- Battery Cycles:
cycles=$(ioreg -l | grep -E -o -m 1 '"Cycle Count"=\d+' | grep -E -o -m 1 "\d+")
"TextOverlay.app/Contents/MacOS/TextOverlay" "Battery cycles:\n$cycles" \
-position "bottom" -duration "4" -fadeInDuration 0.5 -fadeOutDuration 0.5 \
-marginBottom 120 -icon "battery.100percent.circle" -iconRenderingMode "palette" \
-iconColor "primary,green" -colorScheme "inverted" > /dev/null &
- Disk Space:
TextOverlay.app/Contents/MacOS/TextOverlay "${DiskUsage}" \
-position "bottom" -marginBottom 120 -textAlign "left" \
-title "Available Disk Space" -titleAlign "center" \
-autoDismiss YES -duration "8" -fadeInDuration 0.4 -fadeOutDuration 0.5 \
-icon "internaldrive.fill" -colorScheme "inverted" > /dev/null &
- Power Status:
message=""
icon=""
color=""
if [ $(ioreg -l | grep -E -o -m 1 '"ExternalConnected" = Yes' \
| grep -E -o -m 1 "Yes" | wc -l) -ge 1 ];
then
message="Battery Charger Connected"
icon="battery.100percent.bolt"
color="primary,secondary,green"
else
message="Battery Charger Disconnected"
icon="battery.50percent"
color="yellow"
fi
TextOverlay.app/Contents/MacOS/TextOverlay "$message" \
-position "top" -marginTop 110 -autoDismiss YES \
-duration "3.5" -transition "fromTop" -fadeInDuration 0.8 -fadeOutDuration 0.8 \
-icon "$icon" -iconRenderingMode "palette" -iconColor "$color" \
-colorScheme inverted > /dev/null &
- CPU Usage:
"TextOverlay.app/Contents/MacOS/TextOverlay" "$text" \
-position "center" -textAlign "left" -icon "cpu.fill" -transition "scale" \
-fadeInDuration 0.5 -fadeOutDuration 0.3 -autoDismiss YES -duration 6 > /dev/null &
- Weather:
TextOverlay.app/Contents/MacOS/TextOverlay "[${Weather_icon}] ${Weather_name}
[thermometer.medium] ${Weather_temperature}
↓${Weather_low} ↑${Weather_high}
[umbrella.percent.fill] ${Weather_precipitation}" \
-position bottom,center -marginBottom 120 \
-transition scale -fadeInDuration 0.5 -fadeOutDuration 0.3 \
-autoDismiss YES -duration 10 -colorScheme "inverted" > /dev/null &