{"id":22151385,"url":"https://github.com/src-run/serferals","last_synced_at":"2025-07-26T05:31:24.922Z","repository":{"id":691555,"uuid":"335772","full_name":"src-run/serferals","owner":"src-run","description":"Video file management CLI tool that parses ill-formed media file names, looks up movie and episode metadata, subtitles, and other attributes, and outputs a singular media file using a user-defined file hierarchy.","archived":false,"fork":false,"pushed_at":"2022-10-21T20:10:46.000Z","size":426,"stargazers_count":5,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T21:23:18.026Z","etag":null,"topics":["cli","command-line","episode","episode-library","file-parser","lookup","metadata","movie","movie-library","moviedb","php","subtitle","symfony","symfony-console","torrent-files","torrent-management","tvdb"],"latest_commit_sha":null,"homepage":"https://src.run/serferals/readme","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/src-run.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-10-13T08:01:05.000Z","updated_at":"2024-06-16T09:23:35.000Z","dependencies_parsed_at":"2023-01-11T15:47:37.810Z","dependency_job_id":null,"html_url":"https://github.com/src-run/serferals","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/src-run/serferals","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-run%2Fserferals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-run%2Fserferals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-run%2Fserferals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-run%2Fserferals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/src-run","download_url":"https://codeload.github.com/src-run/serferals/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-run%2Fserferals/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267123413,"owners_count":24039456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","episode","episode-library","file-parser","lookup","metadata","movie","movie-library","moviedb","php","subtitle","symfony","symfony-console","torrent-files","torrent-management","tvdb"],"created_at":"2024-12-02T00:32:41.175Z","updated_at":"2025-07-26T05:31:24.665Z","avatar_url":"https://github.com/src-run.png","language":"PHP","readme":"\n# [src-run] serferals\n\n\n[Welcome](https://src.run/go/readme_welcome)! The `src-run/serferals` package provides a CLI application for looking-up\nand organizing media files, with support for movies and TV episodes.\n\nThe following list shows the name of the input files to the left of the output paths this script would move them to on\nthe right.\n\n```txt\nStranger Things S01E01.mkv -\u003e tv/Stranger Things (2016)/Season 01/Stranger Things (2016) [S01E01] Chapter One: The Vanishing Of Will Byers.mkv\nstranger_things_s01e02.mkv -\u003e tv/Stranger Things (2016)/Season 01/Stranger Things (2016) [S01E02] Chapter Two: The Weirdo on Maple Street.mkv\n3:10-To-Yuma-720p-2007.mkv -\u003e movie/3:10 to Yuma (2007)/3:10 to Yuma (2007) [5176].mkv\n```\n\nThis behavior is especially useful for media servers such as [Plex](https://www.plex.tv/downloads/) that require their\nlibrary files follow specific naming conventions. It is also useful for those with OCD-tendencies who require their\narchive of media to be properly and consistently named.\n\n### Customization\n\nThe output file path formats can be easily customized by overwriting the default templates in the `parameters.yml`\nconfiguration file. The default template for TV episodes is the following.\n\n```twig\ntv/{{ 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 }}\n```\n\nYou may recognize the template syntax as [Twig](http://twig.sensiolabs.org/), a widely used template engine in many\nweb frameworks (such as [Symfony](http://symfony.com/), [Drupal](https://www.drupal.org/), and others). While its use\nin this project may be a bit of a \"sledge hammer approach\", it also means that customizing the output file paths is easy\nand straightforward to anyone who's worked with any modern web template language. To further exemplify the simplicity\nof this approach, take a look at the same template as above, but re-formatted with newlines for clarity and displaying\nthe output of each statement in the right-hand side comments, given the following input file\n`Stranger Things (2016) [S01E01] Chapter One: The Vanishing Of Will Byers.mkv`.\n\n```twig\ntv/                           # tv/\n  {{ name|raw }}              # Stranger Things\n  {% if year is defined %}    # \u003ctrue\u003e\n    ({{ year }})              # (2016)\n  {% endif %}\n  /Season {{ season }}/       # Season 01/\n  {{ name|raw }}              # Stranger Things\n  {% if year is defined %}    # \u003ctrue\u003e\n    ({{ year }})              # (2016)\n  {% endif %}\n  [                           # [\n    S{{ season }}             # S01\n    E{{ start }}              # E01\n    {% if end is defined %}   # \u003cfalse\u003e\n      -{{ end }}\n    {% endif %}\n  ]                           # ]\n  {% if title is defined %}   # \u003ctrue\u003e\n    {{ title|raw }}           # Chapter One: The Vanishing Of Will Byers\n  {% endif %}\n  .{{ ext }}                  # .mkv\n```\n\n\n## JTT\n\nThis package represents a single project within a [large collection](https://src.run/go/explore) of open-source code\nreleased under the *SR* namespace, comprised of framework-agnostic libraries, and a number of Symfony bundles. These\nprojects are authored and maintained by [Rob Frawley 2nd](https://src.run/rmf) and \n[collaborators](https://src.run/serferals/github_collaborators).\n\n\n## Quick Start\n\n\n### Basic Usage Video\n\n[![Serferals basic usage example](https://src.run/get/images/serferals-thumb-usage.png)](https://src.run/go/serferals-video-usage)\n\n\n### Installation\n\nBefore beginning, ensure you have created an account and requested a free API key from\n[The Movie DB](https://www.themoviedb.org/) website. Once you have an API key, take note of it and enter it when\nprompted by the `make` script.\n\n\u003e **Note**: For the installation to complete successfully, **PHAR archive writing must not be disabled**. To find the\n\u003e location of your configuration file, run `php -i | grep \"Loaded Configuration File\"`. Edit your `php.ini` file,\n\u003e ensuring the variable `phar.readonly` is uncommented and assigned the value `Off`.\n\n```bash\ngit clone https://github.com/robfrawley/serferals.git \u0026\u0026 cd serferals\n./make\n```\n\nIf installation completes without error, the final line of output will be the version string of the serferals command.\n\n```txt\nsrc-run/serferals version 2.2.3 by Rob Frawley 2nd \u003crmf@src.run\u003e (69975c3)\n```\n\n### Troubleshooting\n\nIf you experience issues with the installer script, debug mode can be enabled by defining a bash variable when calling\n`make`.\n\n```bash\nSERFERALS_DEBUG=true ./make\n```\n\nAdditionally, you can enable \"clean installation\" mode, which ensures all dependencies and helper PHARs (Composer, Box)\nare forcefully re-fetched.\n\n```bash\nSERFERALS_CLEAN=true ./make\n```\n\nMoreover, you can enable \"pristine installation\" mode, which forces removal and re-creation of configuration files as\nwell as enables everything from \"clean installation\" mode.\n\n```bash\nSERFERALS_PRISTINE=true ./make\n```\n\nLastly, all the above mentioned environment variables can be passed in any combination.\n\n```bash\nSERFERALS_DEBUG=true SERFERALS_PRISTINE=true ./make\n```\n\n\u003e **Note:** All troubleshooting variables are only checked to see if they are defined or undefined; they are not checked\nfor a specific value. **Their value is irrelevant.** Calling `SERFERALS_DEBUG=false ./make` will enable \"debug mode\"\nbecause the variable is defined.\n\n\n#### Installation Video\n\n[![Serferals installation video](https://src.run/get/images/serferals-thumb-install.png)](https://src.run/go/serferals-video-install)\n\n## Reference\n\nMy prefered CLI usage includes the `-vvv` and `-s` options, enabling verbose output and the \"smart overwrite\" feature.\n\n```bash\nserferals -vvv -s -o /output/path /input/path/foo [...] /input/path/bar\n```\n\nThe only required option is the output path (`-o|--output-path`). At least one input path must be provided as an argument,\nthough you can specify multiple input \npaths if required.\n\n```bash\nserferals --output-path=/output/path /input/path [...]\n```\n\n## Contributing\n\n### Discussion\n\nFor general inquiries or to discuss a broad topic or idea, find \"robfrawley\" on Freenode. He is always happy to \ndiscuss language-level ideas, possible new directions for a project, emerging technologies, as well as the weather.\n\n### Issues\n\nTo report issues or request a new feature, use the [project issue tracker](https://src.run/serferals/github_issues).\nInclude as much information as possible in any bug reports. Feel free to \"ping\" the topic if you don't get a response\nwithin a few days (sometimes Github notification e-mails fall through the cracks).\n\n### Code\n\nYou created additional functionality while utilizing this package? Wonderful: send it back upstream! *Don't hesitate to\nsubmit a pull request!* Your [imagination](https://src.run/go/readme_imagination) and the requirements outlined within\nour [CONTRIBUTING.md](https://src.run/serferals/contributing) file are the only limitations.\n\n\n## License\n\nThis project is licensed under the [MIT License](https://src.run/go/mit), an [FSF](https://src.run/go/fsf)- and \n[OSI](https://src.run/go/osi)-approved, [GPL](https://src.run/go/gpl)-compatible, permissive free software license.\nReview the [LICENSE](https://src.run/serferals/license) file distributed with this source code for additional\ninformation.\n\n\n## API Usage\n\n[![PThe Movie Database](https://src.run/get/images/tmdb-logo-91x81.png)](https://src.run/serferals/packagist)\n\nSerferals episode and movie lookup powered by\n[The Movie Database](https://www.themoviedb.org/)\n[API](http://docs.themoviedb.apiary.io/).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrc-run%2Fserferals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrc-run%2Fserferals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrc-run%2Fserferals/lists"}