TVrank is a library and command-line utility written in Rust for querying and ranking
information about movies and series. It can be used to query a single title or scan media
directories.
Currently, TVrank only supports IMDB's TSV dumps which it automatically downloads,
caches and periodically updates. More work is required to be able to support and cache
live-query services like TMDB and TVDB.
The in-memory database is reasonably fast and its on-disk persistent cache format reasonably efficient.
The library's documentation is badly lacking but there is an example on how to use it.
For now, the command-line utility of TVrank works well and fast enough to be usable
e.g. instead of searching for a title through DuckDuckGo
using something like !imdb TITLE. In case you still want to see the IMDB page for a
title, TVrank will print out a direct link for each search result for direct access from
the terminal.
Note that TVrank depends on the flate2 crate for decompression of IMDB TSV
dumps. flate2 is extremely slow when built in debug mode, so it is recommended to always
run TVrank in release mode unless there are good reasons not to. By default, release
mode is built with debugging information enabled for convenience during development.
For information on how to use the library, see below.
The TVrank command-line interface has a few modes accessible through the use of
sub-commands:
search "KEYWORDS..."to search by keywords.search "KEYWORDS... (YYYY)"to search by keywords in a specific year.search "TITLE (YYYY)" --exactto search for and exact title in a specific year.search "TITLE" --exactto search for an exact title (-ealso means exact).scan-moviesandscan-seriesto make batch queries based on directory scans.markto mark a directory with a title information file (tvrank.json).
To search for a specific title:
$ tvrank search "the great gatsby (2013)" -eTo search for all titles containing "the", "great" and "gatsby" in the year 2013:
$ tvrank search "the great gatsby (2013)"To search based on keywords:
$ tvrank search "the great gatsby"To search based on an exact title:
$ tvrank search "the great gatsby" -eTo query a series directory:
$ tvrank scan-series <SERIES_MEDIA_DIR>Also, by default TVrank will sort by rating, year and title. To instead sort by year,
rating and title, --sort-by-year can be passed before any sub-command:
$ tvrank --sort-by-year search "house of cards"You can also limit the output of movies and series to the top N entries:
$ tvrank search "the great gatsby" --top 2You can change the output format to json or yaml:
$ tvrank search "the great gatsby" --output jsonTVrank can recursively scan directories and print out information about titles it
finds. This is achieved using the scan-movies and scan-series subcommands.
TVrank expects movie directories to be under a top-level movies media directory (herein
called movies), as follows:
movies
├── ...
├── 127 Hours (2010)
├── 12 Mighty Orphans (2021)
├── 12 Monkeys (1995)
├── 12 Years a Slave (2013)
├── 13 Hours The Secret Soldiers of Benghazi (2016)
├── ...
Movie sub-directories are expected to follow the TITLE (YYYY) format where the TITLE
matches either the primary or original movie title.
If a movie sub-directory does not adhere to this format, TVrank will recursively search
it for more titles. An example of that is as follows:
movies
├── ...
├── The Naked Gun
│ ├── The Naked Gun (1988)
│ ├── The Naked Gun 2½ The Smell of Fear (1991)
│ └── The Naked Gun 33 1-3 The Final Insult (1994)
├── ...
TVrank also expects series directories to be under a top-level series media directory
(herein called series) following either TITLE or TITLE (YYYY) format. The TITLE (YYYY) format can be used to easily disambiguate similarly-titled series. Examples:
series
├── ...
├── House of Cards (1990)
├── Killing Eve
├── Kingdom (2019)
├── ...
Sometimes it is impossible to distinguish between titles just from their original/primary title and release year, this is due to multiple movies or series being released during the same year using the same exact title.
To handle this issue, TVrank supports the ability to explicitly provide title
information files (called tvrank.json) under the corresponding title directory. These
files are detected when using the scan-movies and scan-series sub-commands and are
used for exact identification using the title's unique ID.
A tvrank.json file looks like this:
{
"imdb": {
"id": "ttXXXXXXXX"
}
}where "ttXXXXXXXX" is the IMDB title id shown under the IMDB ID column or available as
part of the IMDB URL of a title.
You can ask TVrank to write the title information (tvrank.json) file for you by using
the mark sub-command and passing it the title's directory and ID that you would like to
write.
tvrank mark "movies/The Great Gatsby (2013)" tt1343092This will results in a file called movies/The Great Gatsby (2013)/tvrank.json containing
the following information:
{
"imdb": {
"id": "tt1343092"
}
}If a tvrank.json file already exists, TVrank will refuse to overwrite it. To force
overwriting it, the --force flag can be used.
To print out more information about what the application is doing, use -v before any
sub-command. Multiple occurrences of -v on the command-line will increase the verbosity
level:
$ tvrank -vvv --sort-by-year search "city of god"The following options can come before or after the sub-command. The latter have precedence over the former.
--verbose
--sort-by-year
--force-update
--top <N>
--color
--output [table|json|yaml]To find help, see the help sub-command:
$ tvrank help
$ tvrank help search
$ tvrank help scan-series
$ tvrank help scan-moviesPlease note that the screencast is slightly outdated. Please use the sub-commands described above instead of what is shown in the screencast.
By default, TVrank displays some of the content with color. However, it supports the
NO_COLOR environment variable. When NO_COLOR is set, TVrank will not use color in
its output. This can also be overridden by passing the --color argument on the
command-line:
NO_COLOR=1 tvrank search "the great gatsby" # Without colors
NO_COLOR=1 tvrank search "the great gatsby" --color # With colorsIt is recommended to use the pre-built releases.
Installing TVrank from this repository's sources requires Cargo, a Rust compiler and a
toolchain to be available. Once those are ready and the repository's contents are cloned,
a simple build and install through cargo should suffice:
$ git clone https://github.com/fredmorcos/tvrank
$ cd tvrank
$ cargo install --path cliInstalling TVrank from Crates.io also requires Cargo, a Rust
compiler and a toolchain to be available. Once those are ready, a simple build and install
using cargo should suffice:
$ cargo install tvrank-cli`Add the dependency to your Cargo.toml:
[dependencies]
tvrank = "0.8"Or, using cargo add:
$ cargo add tvrankInclude the Imdb type:
use tvrank::imdb::{Imdb, ImdbQuery};
use tvrank::utils::search::SearchString;Create a directory for the cache using the tempfile crate then create the database
service. The closure passed to the service constructor is a callback for progress updates
and is a FnMut to be able to e.g. mutate a progress bar object.
let cache_dir = tempfile::Builder::new().prefix("tvrank_").tempdir()?;
let imdb = Imdb::new(cache_dir.path(), false, |_, _| {})?;Afterwards, one can query the database using either imdb.by_id(...),
imdb.by_title(...), imdb.by_title_and_year(...) or imdb.by_keywords(...), and print
out some information about the results.
let title = "city of god";
let year = 2002;
println!("Matches for {} and {:?}:", title, year);
let search_string = SearchString::try_from(title)?;
for title in imdb.by_title_and_year(&search_string, year, ImdbQuery::Movies)? {
let id = title.title_id();
println!("ID: {}", id);
println!("Primary name: {}", title.primary_title());
if let Some(original_title) = title.original_title() {
println!("Original name: {}", original_title);
} else {
println!("Original name: N/A");
}
if let Some((rating, votes)) = title.rating() {
println!("Rating: {}/100 ({} votes)", rating, votes);
} else {
println!("Rating: N/A");
}
if let Some(runtime) = title.runtime() {
println!("Runtime: {}", humantime::format_duration(runtime));
} else {
println!("Runtime: N/A");
}
println!("Genres: {}", title.genres());
println!("--");
}See the query.rs example under the lib/examples/query directory for a
fully-functioning version of the above.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent