README.org

#+TITLE: scripts
#+DESCRIPTION: Excerpt of modula t.'s personal script collection.

This is (part of) my personal collection of scripts.

They range in complexity and usefulness; some of them are little more than aliases, while others contain a lot more logic and functionality. They should all support a ~-h~ or ~--help~ argument to display a summary and basic help information (it should be considered a bug if any don't). Some of the scripts have configuration options at the top of the file that you may need or want to change, but I strive for "sensible defaults" and attempt to auto-detect "the right thing" when possible.

Even though I wrote them primarily for myself, all of these scripts should still be usable (and hopefully useful) to others. I have made an effort to write clean code (with comments where warranted), to handle possible error conditions, and to give helpful output when they occur.

The scripts are mostly written in [[https://fishshell.com/][Fish]] (because Fish is great), but a few of them are written in other languages (because other languages are also great, and fun to play with). As long as you have the script's requirements, it should work just as well for you. Please don't hesitate to open an issue if you find any problems with them.

The scripts in this collection that I find most useful are marked with ⚡.

All of the scripts are contained in the ~src/~ directory, but they're also listed below, with their requirements and a synopsis of their functionality.

* utility

Utilities that may be handy for shell-related tasks.

** ~ask-yes-no~ ⚡

/fish/

Ask the user a yes or no question and return true (~0~) if yes, false (~1~) otherwise.

** ~c~ ⚡

/fish, xclip (when on linux)/

A convenient interface to the clipboard.

** ~c-~

/fish/

Alias for ~c -~; copy standard input to the clipboard.

** ~eman~

/fish/

Open a man page in Emacs.

** ~e~

/fish, emacs/

Edit a file in Emacs. If called on a non-local machine, will open the file in the local Emacs via TRAMP.

** ~e-~

/fish, emacs/

Send standard input to an Emacs buffer.

** ~e-fg~

/fish, emacs/

Edit the specified file in Emacs, exiting only once its buffer is closed.

** ~ediff~

/fish, emacs/

Diff files with Emacs' ~ediff~.

** ~eww~

/fish, emacs/

Emacs Web Wowser; open a URL in Emacs' web browser, [[https://www.gnu.org/software/emacs/manual/html_mono/eww.html][eww]].

** ~git-multi-log~

/fish, git/

Merge and sort git log summaries for multiple repos.

** ~http-server~

/fish, python/

Quickly spin up a basic HTTP server for a directory.

** ~qr~

/fish, qrencode/

Generate and display a QR code for the specified text, or generate a QR code to connect to a wifi network.

** ~qrc~

/fish, qr, c/

Generate and display a QR code for the text in the clipboard.

** ~set-title~

/fish/

Set the terminal window title.

** ~set-wallpaper~

/fish, hsetroot, feh/

Set the desktop background, either to a solid color, or to a specified image.

** ~speak~

/fish, espeak, say (when on macos) or flite/

Speak text using a text-to-speech engine.

** ~sshot~ ⚡

/fish, scrot, slop, c/

Take a screenshot of the whole screen, a window, or a(n interactively-selected) region. unlike scrot it doesn't cause junk to show up near the edges of the screenshot.

* files and paths

** ~abbreviate-path~

/fish/

Abbreviate the path passed as an argument. Similar to fish's built-in ~prompt_pwd~ function.

** ~bak~ ⚡

/fish/

Make a ~.bak~ backup copy of the specified file(s).

** ~d~

/fish, trash-put (trash-cli)/

"Delete" (trash) a file, also removing it from any TMSU database.

** ~dirdiff~ ⚡

/fish/

List files that only exist in one of the two specified dirs. This script supports comparing directories over SSH, i.e.: ~dirdiff /path/to/dir host:/path/to/dir~

** ~dirtour~ ⚡

/fish/

Print the first file from each directory in CWD. With an argument, print a random file from each directory instead of the first one.

** ~filter~ ⚡

/raku/

Filter a list of filenames, outputting only those whose extension denotes a specified "type" (i.e. audio, image, video, etc).

** ~find-broken-symlinks~

/fish, find/

Get a list of symlinks whose target does not exist. This is basically just an easier-to-remember alias for ~find -xtype l~.

** ~finda~

/fish, bfs or find/

Find audio files.

** ~findc~

/fish, bfs or find/

Find compressed files.

** ~findd~

/fish, bfs or find/

Find directories.

** ~findi~

/fish, bfs or find/

Find image files.

** ~findmedia~

/fish, bfs or find/

Find media files (audio, images, video).

** ~findtype~

/fish, bfs or find/

Find files of a specified type. This is used by ~finda~, ~findc~, ~findd~, etc; it's simpler to just use those scripts instead of this one directly.

** ~findu~

/fish, bfs or find/

Find unsorted files (anything not found by ~finda~, ~findc~, ~findd~, etc).

** ~findv~

/fish, bfs or find/

Find video files.

** ~findvis~

/fish, bfs or find/

Find visual files (images, video).

** ~fixperms~ ⚡

/fish/

Recursively fix permissions on a file or directory. *BE VERY CAREFUL WITH THIS SCRIPT, AS PERMISSIONS ARE NOT BACKED UP BEFORE THEY'RE CHANGED.*

** ~loc~ ⚡

/fish, bfs or find/

Locate files by searching their names case-insensitively with [[https://github.com/tavianator/bfs][~bfs~]] or ~find~.

** ~locate-dominating-file~ ⚡

/fish/

Look up in the directory hierarchy for a specified file. This can be used, for example, to check if we're in a git repository, by locating ~.git~.

** ~lsa~ ⚡

/fish, bfs or find/

List audio files.

** ~lsc~ ⚡

/fish, bfs or find/

List compressed files.

** ~lsd~ ⚡

/fish, bfs or find/

List directories.

** ~lsi~ ⚡

/fish, bfs or find/

List image files.

** ~lsu~ ⚡

/fish, bfs or find/

List files of an unknown "type"; everything not audio, compressed, directories, images, or video. See also: ~lsa~, ~lsc~, ~lsd~, ~lsi~, ~lsv~, ~lsvis~.

** ~lsv~ ⚡

/fish, bfs or find/

List video files.

** ~lsvis~ ⚡

/fish, bfs or find/

List visual files (images, video).

** ~recently~ ⚡

/fish/

Get a list of recently-modified files in this directory and subdirectories, most recent first.

** ~rfile~ ⚡

/fish/

Output a random file in the current directory. An argument can be provided to specify the number of subdirectories to look for a random file.

** ~tmsu-mv~

/fish, tmsu/

Move a file, then run ~tmsu repair~ for the new name and location.

** ~tmsu-rm~

/fish, tmsu/

Trash or delete a file, then run ~tmsu repair~ to remove it from the database.

** ~tmsu-tag-count~

/fish, tmsu/

Print all TMSU tags next to a count of their uses.

** ~trash-confirm~

/fish, trash-put (trash-cli)/

Ask the user to confirm trashing the specified file(s), then trash them.

* system

** ~check-battery~

/fish, notify-send (libnotify)/

Check the battery and notify if it's low. May be useful to set as a cron job.

** ~check-df~ ⚡

/fish/

Check disk free; print a message if free space of any partitions are below a threshold. May be useful run from your shell init file.

** ~check-memory-usage~

/fish, notify-send (libnotify)/

Check current memory and swap usage and notify if it's low. May be useful to set as a cron job.

** ~clipboard-filter~

/fish, copyevent, xsel/

Automatically apply edits when the clipboard is modified.

By default, the only edits this makes are to remove YouTube's ~&pp=~ tracking parameters from URLs, but it should be pretty easy to add your own.

** ~grep-package-files~

/fish, pacman, rg/

Run ripgrep on all of the files (not directories) installed by a package.

** ~myip~ ⚡

/fish, curl/

Get your current IP address as seen from the public internet.

** ~remove-unneeded-packages~ ⚡

/fish, pacman/

Ask to remove all system packages installed as dependencies that are no longer needed.

** ~ssuspend~

/fish, xset/

"Screen suspend". Simply turns off your monitor(s).

** ~vol~ ⚡

/fish, pactl (libpulse)/

Change system volume. This might be a bit more convenient and intuitive than typing crap like ~amixer -c 2 set PCM +2%~.

* processes

** ~pgr~ ⚡

/fish, grep/

Grep for processes that match the arguments. Similar to ~pgrep~ but its output is meant to be readable by humans.

** ~snds~ ⚡

/fish, grep/

Get a list of all programs using sound devices.

** ~run-if-not~ ⚡

/fish/

Run a program if it's not already running.

** ~xeph~ ⚡

/fish, xephyr/

Run a program in [[https://wiki.archlinux.org/title/Xephyr][Xephyr]], starting it if necessary.

* media

** ~a2v~ ⚡

/fish, ffmpeg/

"Audio to video"; generate a video from a sound file and an image. Useful, for example, if you want to upload music to YouTube or other sites that support videos but not audio.

** ~a2v-multi~

/fish, a2v, parallel/

Run a2v on multiple audio files in parallel using [[https://www.gnu.org/software/parallel/][GNU parallel]]. ~nice~s the processes to run with a lower priority, to not disturb other processes on your system.

** ~auto-rotate-image~

/fish, convert (imagemagick)/

Automatically correct image rotation based on its metadata.

** ~autocrop~

/fish, convert (imagemagick)/

Automatically trim blank edges of an image. Copies the original image to ~/tmp~ first in case it crops incorrectly.

** ~capture-audio~ ⚡

/fish, jack_capture, convert-audio, c/

Capture the audio output going to the speakers and record it to a file.

** ~content-aware-scale~

/fish, convert (imagemagick), ffmpeg, parallel, sox/

Content-aware scale a video. See [[https://www.imagemagick.org/Usage/resize/#liquid-rescale][ImageMagick's documentation]] for more information about what this does, but basically, it can be used to make a video look silly. Examples: [[https://www.youtube.com/watch?v=PwKABG6Wzdo][one]], [[https://www.youtube.com/watch?v=LYbgKh01daA][two]], [[https://www.youtube.com/watch?v=BCxzQF47dYQ][three]]. For good measure, it also applies vibrato to the audio.

** ~convert-audio~ ⚡

/fish, ffmpeg, parallel/

Convert a set of audio files into a specified audio format, preserving tags. Uses GNU Parallel to parallelize the jobs to convert as fast as possible, ~nice~ing the processes to run with a lower priority, to not disturb other processes on your system.

** ~mpls~

/fish, mpc (mpd)/

List tracks in mpd's current playlist.

** ~p~ ⚡

/fish, mpv/

Play media with mpv, joining its twitch chat via IRC (weechat) if it's a twitch stream. Once the stream is stopped, exits the channel.

** ~randomsong~

/fish/

Get a list of N random songs from your music directory.

** ~v~ ⚡

/fish, nsxiv/

View images or directories of images with [[https://github.com/nsxiv/nsxiv][~nsxiv~]]. passes the rest of the images in the directory as well.

** ~v-~

/fish, nsxiv/

Alias for ~v -~; open an image viewer for the files passed via stdin.

* guis

** ~lyrics-gui~ ⚡

/fish, text-gui, lyrics/

Open a window showing the lyrics of MPD's current track.

** ~move-gui~ ⚡

/fish, zenity/

Move a file using a file selector gui. Accepts a list of files either as arguments or from stdin if ~-~ is the first argument.

** ~rename-gui~ ⚡

/fish, zenity/

Rename a file via a GUI popup.

** ~tag-gui~ ⚡

/python, tkinter (tcl/tk), tmsu/

Edit the [[https://github.com/oniony/TMSU][~TMSU~]] tags for the specified file(s) with a tab-completing gui. Shows the filename (or the common directory if tagging multiple) and the previous set of tags, and allows you to edit their tags, with tab-completion of tag names.

** ~text-gui~ ⚡

/python, tkinter (tcl/tk)/

Show arbitrary text in a simple GUI. May be useful in scripts bound to window manager shortcuts or the like. The text is editable, and keybindings can be specified with ~--action~ arguments.

* tools

Scripts for getting information from online services or local tools.

** ~define-selected~ ⚡

/fish, dictd, xclip, text-gui/

Define the specified or selected word, showing the result in a popup dialog.

** ~lyrics~ ⚡

/fish, clyrics, ffprobe (ffmpeg)/

Get the lyrics for the specified or currently-playing song.

** ~synonyms~ ⚡

/fish, dictd/

Get synonyms for a word.

** ~transcribe~ ⚡

/fish, whisper, tesseract, slop, scrot/

Transcribe an audio file, image file, or a selection of the screen to text.

** ~translate-selected~ ⚡

/fish, translate-shell, xclip, text-gui/

Translate the selected text, showing the result in ~text-gui~.