Welcome! The src-run/serferals package provides a CLI application for looking-up
and organizing media files, with support for movies and TV episodes.
The following list shows the name of the input files to the left of the output paths this script would move them to on the right.
Stranger Things S01E01.mkv -> tv/Stranger Things (2016)/Season 01/Stranger Things (2016) [S01E01] Chapter One: The Vanishing Of Will Byers.mkv
stranger_things_s01e02.mkv -> tv/Stranger Things (2016)/Season 01/Stranger Things (2016) [S01E02] Chapter Two: The Weirdo on Maple Street.mkv
3:10-To-Yuma-720p-2007.mkv -> movie/3:10 to Yuma (2007)/3:10 to Yuma (2007) [5176].mkvThis behavior is especially useful for media servers such as Plex that require their library files follow specific naming conventions. It is also useful for those with OCD-tendencies who require their archive of media to be properly and consistently named.
The output file path formats can be easily customized by overwriting the default templates in the parameters.yml
configuration file. The default template for TV episodes is the following.
tv/{{ name|raw }}{% if year is defined %} ({{ year }}){% endif %}/Season {{ season }}/{{ name|raw }}{% if year is defined %} ({{ year }}){% endif %} [S{{ season }}E{{ start }}{% if end is defined %}-{{ end }}{% endif %}]{% if title is defined %} {{ title|raw }}{% endif %}.{{ ext }}You may recognize the template syntax as Twig, a widely used template engine in many
web frameworks (such as Symfony, Drupal, and others). While its use
in this project may be a bit of a "sledge hammer approach", it also means that customizing the output file paths is easy
and straightforward to anyone who's worked with any modern web template language. To further exemplify the simplicity
of this approach, take a look at the same template as above, but re-formatted with newlines for clarity and displaying
the output of each statement in the right-hand side comments, given the following input file
Stranger Things (2016) [S01E01] Chapter One: The Vanishing Of Will Byers.mkv.
tv/ # tv/
{{ name|raw }} # Stranger Things
{% if year is defined %} # <true>
({{ year }}) # (2016)
{% endif %}
/Season {{ season }}/ # Season 01/
{{ name|raw }} # Stranger Things
{% if year is defined %} # <true>
({{ year }}) # (2016)
{% endif %}
[ # [
S{{ season }} # S01
E{{ start }} # E01
{% if end is defined %} # <false>
-{{ end }}
{% endif %}
] # ]
{% if title is defined %} # <true>
{{ title|raw }} # Chapter One: The Vanishing Of Will Byers
{% endif %}
.{{ ext }} # .mkvThis package represents a single project within a large collection of open-source code released under the SR namespace, comprised of framework-agnostic libraries, and a number of Symfony bundles. These projects are authored and maintained by Rob Frawley 2nd and collaborators.
Before beginning, ensure you have created an account and requested a free API key from
The Movie DB website. Once you have an API key, take note of it and enter it when
prompted by the make script.
Note: For the installation to complete successfully, PHAR archive writing must not be disabled. To find the location of your configuration file, run
php -i | grep "Loaded Configuration File". Edit yourphp.inifile, ensuring the variablephar.readonlyis uncommented and assigned the valueOff.
git clone https://github.com/robfrawley/serferals.git && cd serferals
./makeIf installation completes without error, the final line of output will be the version string of the serferals command.
src-run/serferals version 2.2.3 by Rob Frawley 2nd <[email protected]> (69975c3)If you experience issues with the installer script, debug mode can be enabled by defining a bash variable when calling
make.
SERFERALS_DEBUG=true ./makeAdditionally, you can enable "clean installation" mode, which ensures all dependencies and helper PHARs (Composer, Box) are forcefully re-fetched.
SERFERALS_CLEAN=true ./makeMoreover, you can enable "pristine installation" mode, which forces removal and re-creation of configuration files as well as enables everything from "clean installation" mode.
SERFERALS_PRISTINE=true ./makeLastly, all the above mentioned environment variables can be passed in any combination.
SERFERALS_DEBUG=true SERFERALS_PRISTINE=true ./makeNote: All troubleshooting variables are only checked to see if they are defined or undefined; they are not checked for a specific value. Their value is irrelevant. Calling
SERFERALS_DEBUG=false ./makewill enable "debug mode" because the variable is defined.
My prefered CLI usage includes the -vvv and -s options, enabling verbose output and the "smart overwrite" feature.
serferals -vvv -s -o /output/path /input/path/foo [...] /input/path/barThe only required option is the output path (-o|--output-path). At least one input path must be provided as an argument,
though you can specify multiple input
paths if required.
serferals --output-path=/output/path /input/path [...]For general inquiries or to discuss a broad topic or idea, find "robfrawley" on Freenode. He is always happy to discuss language-level ideas, possible new directions for a project, emerging technologies, as well as the weather.
To report issues or request a new feature, use the project issue tracker. Include as much information as possible in any bug reports. Feel free to "ping" the topic if you don't get a response within a few days (sometimes Github notification e-mails fall through the cracks).
You created additional functionality while utilizing this package? Wonderful: send it back upstream! Don't hesitate to submit a pull request! Your imagination and the requirements outlined within our CONTRIBUTING.md file are the only limitations.
This project is licensed under the MIT License, an FSF- and OSI-approved, GPL-compatible, permissive free software license. Review the LICENSE file distributed with this source code for additional information.
Serferals episode and movie lookup powered by The Movie Database API.