Skip to content

About

Bulk upload local photos to a nixplay frame

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

79 Commits

Folders and files

Repository files navigation

nix-upload

A Python utility that automatically uploads photos from your local directory (recursively) to Nixplay digital photo frames. The tool supports batch processing, image resizing, and text overlay with date and location information.

Caution

This script removes existing photos from the target playlist before uploading. Setting delete_my_uploads to true also clears the My uploads album at run start.

How to Install

  1. Prerequisites

    • Python 3.10 or higher and pipx (on Debian/Ubuntu: sudo apt install pipx)
    • Google Chrome or Chromium, installed with your system's package manager (on Debian/Ubuntu, google-chrome-stable from Google's apt repository). This keeps the browser updated and its libraries installed. The script does not download a browser; if none is found it stops with an error. Set CHROME_BIN to use a browser in a non-standard location.
    • A Nixplay account
    • Local directory containing photos to upload
  2. Install a release

    Install a tagged release from GitHub (replace v1.1 with the release you want). The -c option installs the exact package versions pinned in that release's requirements.txt:

    TAG=v1.1
    REPO=https://github.com/joyjit/nix-upload
    RAW=https://raw.githubusercontent.com/joyjit/nix-upload
    pipx install --force \
      --pip-args="-c $RAW/$TAG/requirements.txt" \
      "git+$REPO@$TAG"

    This puts a nix-upload command on your PATH (usually ~/.local/bin/nix-upload). To upgrade or roll back, run the same commands with a different tag.

  3. Create a working directory and config

    • Create a directory for the tool's config, logs and caches, and copy sample_config.json into it as config.json.
    • debug_directory and cache_directory are relative to the directory you run the command from.
  4. Configure the Application

    • Edit config.json with your credentials and preferences
    • Required parameters:
      • username: Your Nixplay account email
      • password: Your Nixplay account password
      • photos_directory: Absolute or relative path to the root folder containing photos (searched recursively)
  5. Run (from the working directory)

    nix-upload

    You can also specify a custom configuration file using the --config (or -c) option:

    nix-upload --config my-custom-config.json

Running from a source checkout (development)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python nix_upload.py --config config.json

requirements.txt is fully pinned (direct and transitive). To change dependencies, edit dependencies in pyproject.toml, install pip-tools, run pip-compile --strip-extras -o requirements.txt pyproject.toml, then commit both files. Dependabot opens a monthly pull request to update the pinned versions.

Configuration Parameters

The script uses a config.json file for configuration. Here are all available parameters:

Required Parameters

  • username: Your Nixplay account email (login identifier)
  • password: Your Nixplay account password
  • photos_directory: Path to the directory containing your photos (no default; must be set in config.json)

Optional Parameters

  • base_url: Nixplay website URL (default: "https://app.nixplay.com")
  • playlist_name: Name of the Nixplay playlist to upload to (default: "nix-upload")
  • delete_my_uploads: Whether to delete your "My uploads" album when the run starts (default: true). sample_config.json sets this to false so new users avoid wiping that album by mistake.
  • max_photos: Maximum number of photos to upload (default: 500)
  • max_file_size_mb: Maximum file size for each photo in MB (default: 3)
  • batch_size: Number of photos to upload in each batch (default: 100)
  • image_width: Target width for resized images (default: 1280)
  • image_height: Target height for resized images (default: 800)
  • log_level: Logging level (default: "INFO")
  • headless: Run browser in headless mode (default: true). If DISPLAY is unset, headless is forced even when set to false.
  • caption: Whether to add text overlay with date and location (default: true)
  • reverse_geocode: When caption is true and GPS is present, call OpenStreetMap Nominatim to resolve place names (default: true). Set to false to caption location as coordinates only and avoid network calls.
  • cache_directory: Directory for the reverse-geocode CSV cache (default: "cache", expanded to an absolute path). Cache file: <cache_directory>/reverse_geocode.csv
  • date_format: Format for date display on photos (default: "%Y-%m-%d %H:%M")
  • caption_position: Position of text overlay ("top" or "bottom", default: "bottom")
  • font_size: Font size for text overlay in points (default: 50)
  • font_path: Path to custom font file (default: null, uses system font)
    • Windows examples:
      • "C:/Windows/Fonts/arial.ttf"
      • "C:/Windows/Fonts/calibri.ttf"
      • "C:/Windows/Fonts/helvetica.ttf"
    • macOS examples:
      • "/Library/Fonts/Arial.ttf"
      • "/Library/Fonts/Helvetica.ttc"
      • "/System/Library/Fonts/Helvetica.ttc"
    • Linux examples:
      • "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
      • "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf"
  • debug_directory: Directory for storing log files and debug snapshots (default: "debug")

Date Format Options

Common date format options for the date_format parameter:

  • "%b %Y" - Month and year (Jan 2024)
  • "%B %Y" - Full month name and year (January 2024)
  • "%b %d, %Y" - Month, day, and year (Jan 15, 2024)
  • "%Y-%m" - Year and month (2024-01)
  • "%m/%Y" - Month and year (01/2024)

Example Configuration

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "photos_directory": "PATH/TO/ROOT/OF/YOUR/PHOTOS/DIR",
    "base_url": "https://app.nixplay.com",
    "playlist_name": "nix-upload",
    "delete_my_uploads": false,
    "max_photos": 500,
    "max_file_size_mb": 3,
    "batch_size": 100,
    "image_width": 1280,
    "image_height": 800,
    "log_level": "INFO",
    "headless": true,
    "caption": true,
    "reverse_geocode": true,
    "cache_directory": "cache",
    "caption_position": "bottom",
    "date_format": "%b %Y",
    "font_size": 50,
    "font_path": "C:/Windows/Fonts/arial.ttf",
    "debug_directory": "debug"
}

To run:

  1. Open a command shell in your working directory (the one with config.json)
  2. Run nix-upload
    • Optionally specify a custom config file: nix-upload --config my-config.json

Running on a schedule (cron)

cron starts jobs with a minimal PATH, so use the full path to the command and cd into the working directory first (so config.json, debug_directory and cache_directory resolve there). Example, every other day at 22:00:

0 22 */2 * * cd /opt/nix-upload && $HOME/.local/bin/nix-upload

Run which nix-upload to find the path on your system.

Upgrading from an older version

Versions before v1.1 were run by copying nix-upload.py and installing requirements.txt into a virtual environment. From v1.1:

  • The script file is now nix_upload.py (Python modules can't contain a dash), and it is installed as the nix-upload command with pipx (see How to Install). Keep your existing working directory and config.json; only the install and the command you run change.
  • The script no longer downloads its own copy of Chrome. Install Chrome with your package manager first. Older versions kept that copy in ~/.cache/nix-upload/chrome-for-testing (or <working directory>/.cache/chrome-for-testing); you can delete it. Keep any reverse_geocode.csv cache file.
  • Update any cron job or wrapper script to call nix-upload instead of python nix-upload.py.

Troubleshooting

  • "No Chrome/Chromium browser found": install Google Chrome or Chromium with your package manager, or set the CHROME_BIN environment variable to the browser binary.
  • "session not created: Chrome instance exited" or missing .so libraries: the browser's system libraries are missing. Reinstalling the browser package (e.g. sudo apt install --reinstall google-chrome-stable) brings them back.
  • Logs and screenshots of failures are saved in debug_directory.

NOTE

The script clears the target playlist before uploading (so previous photos in that playlist are removed). If delete_my_uploads is true, it also clears the separate My uploads album at the start of the run.

Caution

Setting delete_my_uploads to true deletes content in the My uploads album. Clearing the playlist happens regardless when the run proceeds to upload.

Known issues:

  • I don't know why this warning shows, but it seems to be a benign message "Attempting to use a delegate that only supports static-sized tensors with a graph that has dynamic-sized tensors (tensor#-1 is a dynamic-sized tensor)."
  • In your config.json file, set "max_photos" to not more than 1900, and "batch_size" to not more than 100, for best performance

License

Apache License 2.0

Disclaimer

Use at your own Risk

About

Bulk upload local photos to a nixplay frame

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages