Metadata-Version: 2.3
Name: plasma-apod-wallpaper
Version: 1.0.0
Summary: KDE Plasma wallpaper that displays the daily NASA APOD from science.nasa.gov
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Plasma APOD Wallpaper

A Plasma 6 wallpaper that displays NASA's Astronomy Picture of the Day (APOD).
It supports still images and looping videos. The command-line tool downloads the
daily media, and the wallpaper reads the downloaded files from a local cache.

## Requirements

- KDE Plasma 6
- Python 3.13 or newer
- `uv`
- `ffmpeg` and `ffprobe` from an FFmpeg package
- `systemctl` with an active user systemd session
- `kpackagetool6` from KDE Plasma 6

The computer must have network access to `science.nasa.gov` to fetch APOD media.

## Install

Install the CLI with uv, then use the CLI to install the wallpaper and its
scheduled fetch service:

```sh
uv tool install plasma-apod-wallpaper
plasma-apod-wallpaper install
```

If the CLI is already installed, upgrade it before running setup:

```sh
uv tool upgrade plasma-apod-wallpaper
plasma-apod-wallpaper install
```

The `install` command installs the Plasma wallpaper package, creates a user
systemd service and timer, and writes the QML environment setting. The timer
starts at 04:05 UTC and retries hourly afterward. The fetcher uses NASA's APOD
WordPress API with its public `DEMO_KEY`; a current manifest avoids repeat API
requests after a successful fetch.

Log out and back in, or restart Plasma, to apply the QML environment setting.
Then run `systemsettings`, open **Wallpaper**, and select **APOD Wallpaper**.

## Use

The timer fetches APOD automatically. To fetch it immediately, run:

```sh
plasma-apod-wallpaper fetch
```

Running the command without a subcommand also fetches APOD:

```sh
plasma-apod-wallpaper
```

The Plasma wallpaper reads the manifest and media files from
`~/.cache/plasma-apod-wallpaper`. Multiple images are displayed in a rotating
slideshow; videos loop as the wallpaper. The cache remains on disk after
uninstall.

Image URLs come from the API's `basic_html`, including both images on rollover
days; a matching `hdurl` upgrades the matching image. Video entries use the
direct video source in `basic_html`, not the `hdurl` snapshot.

Fetch warnings and errors are appended to
`~/.cache/plasma-apod-wallpaper/fetch.log.gz`. The log is gzip-compressed. A
successful fetch adds one summary line.

Older installs may have data in `~/.cache/apodvideo`. The new cache does not
import that data; run `plasma-apod-wallpaper cleanup-legacy` to remove it.

## Uninstall

Remove the Plasma provider and disable its timer with:

```sh
plasma-apod-wallpaper uninstall
```

By default, `uninstall` keeps the cache and setup files. Add `--delete-cache` to
delete the current and old cache directories. Add `--delete-settings` to remove
the user service, timer, and QML environment setting. You can use both options:

```sh
plasma-apod-wallpaper uninstall --delete-cache --delete-settings
```

To remove the old `~/.cache/apodvideo` cache and leftover setup settings without
removing the current wallpaper provider or cache, run:

```sh
plasma-apod-wallpaper cleanup-legacy
```

This cleanup disables scheduled fetching. If you want to keep using the
wallpaper, run `plasma-apod-wallpaper install` again to restore its service and
environment setting. `uninstall` and `cleanup-legacy` leave the CLI installed.
To also remove the CLI, run:

```sh
uv tool uninstall plasma-apod-wallpaper
```

Log out and back in, or restart Plasma, to remove the environment setting from
the running session.

## Help and troubleshooting

Show the available commands and examples:

```sh
plasma-apod-wallpaper --help
plasma-apod-wallpaper fetch --help
```

Check the timer and recent fetch logs with systemd:

```sh
systemctl --user status plasma-apod-wallpaper.timer
systemctl --user list-timers plasma-apod-wallpaper.timer
journalctl --user -u plasma-apod-wallpaper.service
```

Read the compressed fetch log with:

```sh
gzip -dc ~/.cache/plasma-apod-wallpaper/fetch.log.gz
```

If `install` reports missing tools, install FFmpeg and KDE Plasma 6 package
tools, then run `plasma-apod-wallpaper install` again. If the wallpaper does not
appear in System Settings, restart Plasma, run `systemsettings`, and check the
Wallpaper selector again.
