search-in-subs.1

.TH SEARCH-IN-SUBS 1 2024 SEARCH-IN-SUBS\ 0.2.5

.SH NAME
search-in-subs \- search for words in subtitle files

.SH SYNOPSIS
.SY
\fBsearch-in-subs\fR [<options>] \fB-t\fR <search term> ... [<file|dir> ...]
.YS

.SH DESCRIPTION
\fBsearch-in-subs\fR allows the user to search for text in SRT subtitle files. 

At least one search term must be specified to run a search (see \fB-t, --search-term\fR). If no <file|dir> argument is given, a glob pattern set with the \fB-g, --default-glob\fR option is used to match subtitle files. If a <file|dir> argument is a directory, files matching the default glob pattern in that directory are added to the search.

The built-in value of \fB-g, --default-glob\fR is `*.srt`, which matches all files with the `.srt` extension in the current working directory. That value can be changed to any other glob pattern in the configuration file (see FILES below).

Shell options `nullglob`, `extglob` and `globstar` are enabled internally in \fBsearch-in-subs\fR, so shell globbing can be used to its full capacity when setting \fB-g, --default-glob\fR. For example, to match all `.srt` files in the current working directory recursively, including all of its subdirectories, one could set \fB-g, --default-glob\fR to `**/*.srt`.

\fBsearch-in-subs\fR can also gather statistics on searches that it runs. Try running a search with the \fB-s, --stats\fR option set. For more information, see STATISTICS below.

.SS mpv EDL generation

\fBsearch-in-subs\fR can generate EDL files for \fBmpv\fR player, and play the search results using it. To use this functionality, \fBmpv\fR, \fBffmpeg\fR and \fBlua\fR (v5.4) must be installed and available on system's PATH.

In order to generate the EDL files, a video or audio file must exist in the same directory as the subtitle file(s) on which the search is performed. The video or audio file must have the same name as the subtitle file, minus the `.srt` extension and potentially a secondary extension containing a language code, e.g. `.en.srt`. If both video and audio files are found, video files take precedence. If multiple video or audio files are found, the first one will be chosen for use in the generated EDL files.

See \fB--edl-*\fR options below for more information.

More information on mpv EDL format can be found at <https://github.com/mpv-player/mpv/blob/master/DOCS/edl-mpv.rst>.

.SH OPTIONS

.SS Passing arguments to options

Enhanced \fBgetopt\fR syntax applies when passing options. There is one important point to highlight when it comes to passing options with required vs optional arguments.

In case of a short option, if an option takes a *required* argument, the argument may be written as a separate parameter, *or* directly after the option character. If an option takes an *optional* argument, however, the argument *must* be written directly after the option character.

In case of a long option, if an option takes a *required* argument, the argument may be written as a separate parameter, *or* directly after the option name, separated by an equals sign (`=`). If an option takes an *optional* argument, however, the argument *must* be writtent directly after the option name, separated by an equals sign (`=`).

.TS
tab(|);
l l l .
|Short option|Long option
Required argument|\fB-o\fR <value>|\fB--option\fR <value>
|\fB-o\fR<value>|\fB--option\fR=<value>
Optional argument|\fB-o\fR[<value>]|\fB--option\fR[=<value>]
.TE

Options that take optional arguments can be recognized in the options list below by their <value> and the preceding equals sign being enclosed in square brackets:

.EX
\fB-o, --option\fR[=<value>]
.EE

.SS General

.TP
.B -t, --search-term\fR=<search term>
Text to search for. Can be a fixed string or a regular expression depending on the \fB-r, --regex\fR / \fB-R, --no-regex\fR options.

At least one search term must be given to perform a search. Setting this option multiple times sets multiple search terms.

.TP
.B -g, --default-glob\fR=<glob pattern>
A shell glob pattern to use when no <file|dir> arguments are specified, or when a <file|dir> argument is a directory. The default is `*.srt`.

Shell options `nullglob`, `extglob` and `globstar` are enabled internally in \fBsearch-in-subs\fR, thus the default glob pattern is sensitive to those options.  

.TP
.B -v, --verbose
Print the filename even if there were no matches found in that file.

.TP
.B -V, --no-verbose
Print filenames only for files that had matches. This is the default.

.TP
.B -i, --inverse
Only print the names of the files where no matches were found.

.TP
.B -I, --no-inverse
Do not supress printing of matches and names of the files where matches were found. This is the default.

.TP
.B -q, --quiet
Do not print any matches or filenames. Useful, for example, if one only wishes to see the statistics or the exit code.

.TP
.B -Q, --no-quiet
Do not suppress printing of matches or filenames. This is the default.

.TP
.B -r, --regex
Use regular expressions instead of fixed strings in <search term>s.

Also see REGULAR EXPESSIONS below.

.TP
.B -R, --no-regex
Use fixed strings instead of regular expressions in <search term>s. This is the default.

.TP
.B -c, --match-case
Make the search case-sensitive.

.TP
.B -C, --no-match-case
Make the search case-insensitive. This is the default.

.TP
.B -e, --exact-whitespace
Match whitespace characters exactly as specified in the <search term>.

.TP
.B -E, --no-exact-whitespace
Treat all whitespace characters the same during search \- ignoring the type of whitespace character, and how many of them appear in a sequence. This is the default.

Whitespace characters are: space, newline, carriage return, horizontal tab, vertical tab and form feed (POSIX Extended Regular Expressions `[:space:]` character class).

.SS Statistics

.TP
.B -s, --stats
Show match statistics after search.

See STATISTICS below for more information.

.TP
.B -S, --no-stats
Do not show match statistics after search. This is the default.

.TP
.B -h, --stats-headers
Show headers in the statistics table. This is the default.

.TP
.B -H, --stats-no-headers
Do not show headers in the statistics table.

.TP
.B -m, --stats-headers-compact
Compactify headers in the statistics table.

.TP
.B -M, --stats-headers-no-compact
Do not compactify headers in the statistics table. This is the default.

.TP
.B -n, --stats-headers-file-numbers
Show file numbers in the headers of the statistics table. This is the default.

.TP
.B -N, --stats-headers-no-file-numbers
Do not show file numbers in the headers of the statistics table.

.TP
.B -w, --stats-wrap-filenames
Wrap filenames in the statistics table. This is the default.

The table always fits the width of the terminal screen, but filenames may be printed on multiple lines.

.TP
.B -W, --stats-no-wrap-filenames
Do not wrap filenames in the statistics table.

Files are always printed one per row, regardless of whether the table fits the width of the terminal screen.

.SS mpv EDL generation

.TP
.B -p, --edl-play
Play search results in \fBmpv\fR.

Unless \fB-f, --edl-save-files-relative\fR or \fB-F, --edl-save-files-absolute\fR is used together with this option, temporary EDL files are generated and saved in the cache directory (see FILES for more information). The \fB-k, --edl-keep-temporary\fR and \fB-K, --edl-no-keep-temporary\fR options control whether or the temporary EDL files are deleted or kept after \fBmpv\fR player closes.

If \fB-f, --edl-save-files-relative\fR or \fB-F, --edl-save-files-absolute\fR is used together with \fB-p, --edl-play\fR, then temporary files are not generated and the saved EDL files are played.

.TP
.B -P, --edl-no-play
Do not play search results in \fBmpv\fR. This is the default.

.TP
.B -k, --edl-play-keep-temporary
Keep temporary EDL files that are created to play search results in \fBmpv\fR.

.TP
.B -K, --edl-play-no-keep-temporary
Do not keep temporary EDL files that are created to play search results in \fBmpv\fR. This is the default.

The temporary files are deleted right after \fBmpv\fR player closes.

.TP
.B -b, --edl-play-before\fR=<value>
Add a specified amount of time before each segment when generating EDL files. <value> is in seconds. Precise values with a decimal separator are allowed. The default <value> is `0`.

.TP
.B -a, --edl-play-after\fR=<value>
Add a specified amount of time after each segment when generating EDL files. <value> is in seconds. Precise values with a decimal separator are allowed. The default <value> is `0`.

.TP
.B -f, --edl-save-files-relative\fR[={<path>[/]|<path>/<name>.edl|<name>.edl}]
Save EDL files that use relative paths to refer to source files. The default value is unset. When omitted, the value is ``.

If <path> is not given, the EDL files are saved to the current working directory. If <name> is not given, the name `search_results.edl` will be used.

A `.edl` extension after <name> is required because it serves to distinguish a directory called "<name>" from a name of an EDL file. To save to a directory whose name ends in `.edl` (without specifying <name>.edl), add a trailing forward slash (`/`) after <path>.

.TP
.B -F, --edl-save-files-absolute\fR[={<path>[/]|<path>/<name>.edl|<name>.edl}]
Save EDL files that use absolute paths to refer to source files. The default value is unset. When omitted, the value is ``.

See \fB-f, --edl-save-files-relative\fR for information on usage of <path> and <name> values.

.TP
.B --edl-no-save-files
Do not save EDL files, but generate temporary files instead. This is the default.

This option disables \fB-f, --edl-save-files-relative\fR / \fB-F, --edl-save-files-absolute\fR.

.TP
.B -d, --edl-save-mkdir
Create the EDL save directory (the <path> value of \fB--edl-save-files-*\fR options) if it does not exist.

.TP
.B -D, --edl-save-no-mkdir
Do not create the EDL save directory (the <path> value of \fB--edl-save-files-*\fR options) if it does not exist. This is the default.

.TP
.B -y, --edl-save-overwrite
Allow overwriting existing files when saving EDL files.

.TP
.B -Y, --edl-save-no-overwrite
Do not allow overwriting existing files when saving EDL files. This is the default.

.TP
.B -o, --edl-ignore-missing
Omit segments with missing videos when generating EDL files. This is the default.

If set, a warning message is shown listing subtitle files for which no corresponding video file could be identified, but EDL files are still generated if at least one relevant video file was able to be found.

.TP
.B -O, --edl-no-ignore-missing
Do not omit segments with missing videos when generating EDL files.

If set, an error message is shown listing subtitle files for which no corresponding video file could be identified, In this case, no EDL files are generated, and \fBsearch-in-subs\fR exits with exit code `3`.

.TP
.B -u, --edl-structure\fR=<value>
Determines the structure of the set of generated EDL files. <value> can be `flat`, `subdir`, `subdir_hidden`, `subdir_except_chapters` or `subdir_hidden_except_chapters`. The default <value> is `flat`.

.TP
.B --mpv-opts=[:[:]]<opts>
Options to \fBmpv\fR player.

<opts> is an option string that follows \fBxargs\fR quoting. It can be preceded by a single colon, double colon, or nothing.

The leading colons control whether <opts> get appended to previously set options, or replace them.

The phrase 'previously set options' refers to either the default value of <opts> set by \fBsearch-in-subs\fR itself (``), or a value set in the configuration file.

When a single colon (`:`) is used, <opts> replace the previously set options.

When a double colon (`::`) is used, <opts> are appended to the previously set options.

When the leading colons are omitted, whether <opts> replace the previously set options, or are appended to them is determined by an *additonal* value that is yet again set either by \fBsearch-in-subs\fR itself (append), or in the configuration file.

.SS Other

.TP
.B --color
Colorize the output. This is the default.

.TP
.B --no-color
Disable colorization of the output.

.TP
.B --help
Print help.

.TP
.B --version
Print version information.

.SH REGULAR EXPRESSIONS

The regular expressions used are POSIX Extended Regular Expressions as implemented in GNU sed. More information on POSIX Regular Expressions can be found at <https://www.gnu.org/software/grep/manual/html_node/Regular-Expressions.html>.

.SH STATISTICS

If the \fB-s, --stats\fR option is enabled, \fBsearch-in-subs\fR gathers statistics on the search that it performs and displays those statistics in a table at the end of the output.

The \fBMatched\fR, \fBTotal\fR, \fBUnmatched\fR and \fBMatched %\fR columns of that table contain the following data: 

In the file rows: 

.TS
l l .
\fBMatched\fR	Number of subtitles in the file that had matches.
\fBTotal\fR	Total number of subtitles in the file.
\fBUnmatched\fR	Number of subtitles in the file that did not have matches.
\fBMatched %\fR	Percentage of subtitles in the file that had matches.
.TE

In the \fBAverage\fR row: 

.TS
l l .
\fBMatched\fR	Average number of subtitles per file that had matches.
\fBTotal\fR	Average number of subtitles per file.
\fBUnmatched\fR	Average number of subtitles per file that did not have matches.
\fBMatched %\fR	Average percentage of subtitles per file that had matches.
.TE

In the \fBTotal\fR row: 

.TS
l l .
\fBMatched\fR	Total number of subtitles in all files that had matches.
\fBTotal\fR	Total number of subtitles in all files.
\fBUnmatched\fR	Total number of subtitles in all files that did not have matches.
\fBMatched %\fR	Total percentage of subtitles in all files that had matches.
.TE

In the \fBFile\fR column of the \fBTotal\fR row, information is presented in the following format:

\fB<Matched>\fR / \fB<Total>\fR (\fB<Unmatched>\fR) \fB<Matched %>\fR

Where the <placeholder> values represent the following:

.TS
l l .
\fB<Matched>\fR	Total number of files that had matches.
\fB<Total>\fR	Total number of files.
\fB<Unmatched>\fR	Total number of files that did not have matches.
\fB<Matched %>\fR	Percentage of files that had matches.
.TE


.SH FILES

A configuration file can be used to set default options.

The configuration file's location is \fI$XDG_CONFIG_HOME/search-in-subs/config.bash\fR. If \fIXDG_CONFIG_HOME\fR is not set, it defaults to \fI~/.config\fR.

Temporary EDL files that are generated when using the \fB-p, --edl-play\fR option are stored in a cache directory.

The cache directory's location is \fI$XDG_CACHE_HOME/search-in-subs\fR. If \fIXDG_CACHE_HOME\fR is not set, it defaults to \fI~/.cache\fR.

.SH EXIT CODES

\fBsearch-in-subs\fR returns the following exit codes:

.TS
l l .
\fB0\fR	Success. No errors have occured, and at least one match was found.
\fB1\fR	A general error has occured.
\fB2\fR	No matches were found.
\fB3\fR	EDL generation failed. Can only occur if \fB-O, --edl-no-ignore-missing\fR is set.
.TE

.SH AUTHOR

Alex Rogers <https://github.com/linguisticmind>

.SH HOMEPAGE

<https://github.com/linguisticmind/search-in-subs>

.SH COPYRIGHT

Copyright © 2024 Alex Rogers. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.