--filter and fine-tuning

[rednoah]

The --filter option is probably the the most powerful, yet least used option the CLI has to offer. As long as everything "just works" you will never need --filter but if you get mismatches then --filter will allow you to pass in arbitrary rules to help FileBot make the correct match. Plus, once you're familiar with format expressions you'll immediately get filter expressions.

The --filter expression allows you to control which episode or movie object is considered for matching. So if one show is confused with another due to bad naming or missing data you can simply exclude the bad one.

Examples

If you want to process files from a specific season, then you can force a match from that specific season:

Shell: Select all

--filter "s == 2"

If you only process recently aired episodes you could exclude any episode of any show that has been aired more than a few days ago, immediately eliminating any and all potential mismatches with similarly named TV Shows aired at different times:

Shell: Select all

--filter "age < 5"

A more advanced version of the above might only include episode data of recently aired episodes if there are any recently aired episodes, but otherwise default to accepting any episode data:

Shell: Select all

--filter "age < 5 || 5 <= model.age.min()"

If you only process recently aired episodes, then you can focus on episodes aired this year:

Shell: Select all

--filter "d.year >= today.year"

If short movies are giving you trouble, then you can focus on long movies:

Shell: Select all

--filter "runtime >= 60"

If older TV shows are giving you trouble, then you can focus on recent TV shows:

Shell: Select all

--filter "y > 2010"

If misleading data from a specific series is making trouble you can simply exclude it:

Shell: Select all

--filter "none{ n =~ /Crime Scene Investigation/ }"

You can manage a list of explicitly excluded (or included) series names with an external text file:

Shell: Select all

--filter "none{ n in lines('excludes.txt') }"

Console Output: Select all

$ cat *.txt
Magnum, P.I.
CSI: Crime Scene Investigation

You can manage a list of explicitly excluded (or included) series IDs with an external TSV table:

Shell: Select all

--filter "none{ id in csv('ids.tsv') }"

Console Output: Select all

$ cat *.tsv
734	Magnum, P.I. (1980)
1431	CSI: Crime Scene Investigation (2000)

Note that '...' cannot be used to quote argument values in Windows CMD scripts.

Note that ! cannot be used in argument values that are quoted with "..." in Unix shell scripts. Please read Cmdline and Argument Passing for details. Consider using the @file syntax for reading command-line arguments from external text files.

Advanced Usage

--filter expressions can be passed via external *.groovy files:

Shell: Select all

--filter /path/to/Filter.groovy

Since filter expressions allow arbitrary code, you can come up with more smart or more specialized logic yourself. Sharing is caring.

Prototyping and Testing

You can prototype your custom filter expression with the filebot -list command:

Console Output: Select all

$ filebot -list --q "One Piece" --filter "{age < 7}" --format "{today} | {n} | {sxe} | {airdate} | {age} | {age < 7}"
Apply filter [{age < 7}] on [1151] options
Include [One Piece - 22x1118 - The Holy Land in Tumult! Sai and Leo's Full-Power Blow!]
[1] option remaining
2024-09-11 | One Piece | 22x1118 | 2024-09-08 | 3 | true

You can prototype and test your custom filter expression in the FileBot Desktop application, either in the Format Editor to test on one item at a time or in the List Editor to test on multiple items at once: