Metadata-Version: 2.4
Name: mopidy-webdav
Version: 0.1.1
Summary: Mopidy extension for playing music from WebDAV servers, such as Nextcloud.
Author-email: Will Hunt <git@half-shot.uk>
License-Expression: MIT
Project-URL: Homepage, https://codeberg.org/Half-Shot/mopidy-webdav
Project-URL: Source, https://codeberg.org/Half-Shot/mopidy-webdav
Project-URL: Issues, https://codeberg.org/Half-Shot/mopidy-webdav/issues
Keywords: mopidy,webdav,nextcloud,music
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mopidy>=4.0.0
Requires-Dist: pykka>=4.1
Requires-Dist: requests>=2.32
Requires-Dist: mutagen>=1.48
Requires-Dist: pydantic>=2.0
Dynamic: license-file

# mopidy-webdav

[Mopidy](https://mopidy.com/) extension for browsing and playing music stored on a WebDAV
server, such as [Nextcloud](https://nextcloud.com/).

Tracks are fetched on demand and kept in a local cache, so music doesn't need to be synced to
the machine running Mopidy. The library is indexed locally, either when the user browses or
via background workers. 

## Requirements

- Python 3.13+
- Mopidy 4.0+
- A WebDAV server (that supports `PROPFIND` and HTTP basic authentication).

### Format requirements

Since this extension also builds an index, support for new formats is added as needed. We
currently support:

- FLAC
- MP3
- Ogg Opus / Ogg Vorbis
- WAV

Adding a new format is as simple as updating [tracks.py](src/mopidy_webdav/tracks.py).

## Installation

Install into the same Python environment as Mopidy:

```sh
python3 -m pip install mopidy-webdav
```

## Configuration

Add a `[webdav]` section to your Mopidy configuration file. At minimum, `url`, `username` and
`password` must be set.

```ini
[webdav]
url = https://cloud.example.com/remote.php/dav/files/alice
username = alice
password = xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
path = /Music
```

For Nextcloud, the WebDAV URL is `https://<server>/remote.php/dav/files/<user>`. It's
recommended to create an
[App Password](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#managing-devices)
for Mopidy rather than using your account password.

Always use an `https://` URL. Credentials are sent with HTTP basic authentication, so over plain
`http://` anyone on the network can read your password and tamper with responses.

| Option            | Default  | Description                                                                                      |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `enabled`         | `true`   |                                                                                                  |
| `url`             |          | Root URL of the WebDAV server. Varies by implementation                                          |
| `username`        |          | Username for the WebDAV server.                                                                  |
| `password`        |          | Password for the WebDAV server.                                                                  |
| `path`            | `/Music` | Directory, relative to `url`, that contains your music. This is the root shown when browsing.    |
| `max_cache_size`  |          | Maximum total size in bytes of downloaded tracks kept in the cache. Leave empty for no limit.    |
| `prefill_cache`   | `false`  | Walk the whole library on startup, caching track metadata in the background.                     |
| `prefill_workers` | `2`      | Number of concurrent requests used while prefilling the cache.                                   |

Downloaded tracks and cached metadata are stored in `webdav-cache` inside Mopidy's
`core/cache_dir`. Least recently downloaded tracks are removed once `max_cache_size` is
exceeded.

## Development

This project uses [uv](https://docs.astral.sh/uv/).

```sh
uv sync
uv run tox
```

To run Mopidy against a real server, put your settings in `dev.conf` (or any `*.local.conf`)
and run `uv run mopidy --config dev.conf`. These files are gitignored and are excluded from
built packages, so credentials never get published.

### Releasing

Releases are versioned from git tags. Pushing a `vX.Y.Z` tag to Codeberg runs the tests, builds
the package and publishes it to PyPI.

## License

[MIT](LICENSE)
