javdb-python

Search JAVDatabase, export movie metadata as JSON or Kodi NFO, and download posters and preview images.

Requires Python 3.11+. No runtime dependencies.

Install

python -m pip install javdb

From a local checkout:

python -m pip install .

CLI

Use javdb or python -m javdb.

# Interactive search
javdb

# Save movie metadata as NFO or JSON
javdb -q SONE-763 -o movie.nfo
javdb -q SONE-763 --json -o movie.json

# Fetch a movie directly
javdb -l https://www.javdatabase.com/movies/sone-763/ --json

# List search results across up to three pages
javdb -q 'search words' --search --json --pages 3

# Select a result without prompting
javdb -q 'search words' --first --json
javdb -q 'search words' --select 2 -o movie.nfo

# Save metadata and artwork to a directory
javdb -q SONE-763 -d --directory ./movies/SONE-763

A single result or exact movie ID match is selected automatically. Otherwise, choose a numbered result interactively, or use --first / --select N in scripts.

--first and --select are mutually exclusive. Pagination and selection apply to searches. --search supports query, pagination, JSON, and output options; it cannot be combined with direct links, selection, or artwork/directory options.

Output

Metadata goes to stdout unless a file or directory is specified. Progress and errors go to stderr. -o FILE writes only to that file; -o - forces stdout.

--directory DIR saves metadata there, with or without artwork. With -d alone, the directory is ./<DVD-ID>/, falling back to a sanitized title. Default files:

SONE-763/
  SONE-763.nfo          # metadata.json with --json
  artwork/
    poster.jpg
    preview-001.jpg
    preview-002.jpg

Image extensions follow their URLs. If exactly one video in the chosen directory matches the DVD ID, its filename stem is used for the NFO. -o overrides the metadata path independently of the artwork directory.

Existing metadata requires --overwrite; existing artwork is reused unless that flag is supplied. NFO uses local paths for downloaded artwork and remote URLs otherwise. JSON always keeps remote URLs. Trailer URLs are included as metadata; only images are downloaded.

Exit codes: 0 success, 1 request/parsing/file failure, 2 invalid arguments, 130 cancellation. A failed image download still allows metadata to be saved with its remote URL, but returns 1.

Python API

from javdb import Client, JavDBError, to_json, to_nfo

client = Client(timeout=15, retries=2)

try:
    results = client.search("SONE-763", page=1, pages=2)
    if results:
        movie = client.movie(results[0]["link"])
        print(to_json(movie))
        print(to_nfo(movie))

        if movie["poster"]:
            client.download(movie["poster"], "poster.jpg", overwrite=False)
except (JavDBError, OSError, ValueError) as error:
    print(error)

Import these classes and functions directly from javdb. Pass the source URL to the HTML parsers to resolve relative links; the default is https://www.javdatabase.com/. Standalone parsers allow incomplete metadata; client.movie() raises JavDBError for unrecognized movie pages.

Network/parsing failures raise JavDBError, invalid parameters raise ValueError, and file errors raise OSError subclasses. Library calls do not print or prompt.

Returned data

Search results contain code, title, link, date, studio, and poster (cover thumbnail URL). For entries without a DVD ID, code is the card heading.

Movie dictionaries contain:

Missing values are None (null in JSON); missing lists are empty. Unrated movies have rating=None. NFO omits unavailable fields and converts runtime to minutes.

Development

Run the offline tests with no additional dependencies:

PYTHONPATH=src python3 -m unittest discover -s tests -v

License

MIT