Metadata-Version: 2.4
Name: mastodon-bookmarkmedia
Version: 0.8.1
Summary: Download and archive media from Mastodon bookmarks
Author: Philipp Bielefeldt
Author-email: philipp@bielefeldt.online
License: MPL-2.0
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Mastodon.py>=2.0.0
Requires-Dist: python-dotenv
Requires-Dist: python-magic
Requires-Dist: requests
Requires-Dist: blurhash
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 📚 Mastodon Bookmark Media Downloader

A command-line tool that downloads and archives **image and video attachments** from your **Mastodon bookmarks**, including support for remote-URL fallback, filename sanitization, and extension correction.
Useful for archiving media before it's deleted or expires on remote instances.


## ✨ Features

* Downloads all images and videos from bookmarked posts
* Supports filtering (`image`, `video`, or `all`)
* Saves media with clean, traceable filenames (based on user, instance, and post ID)
* Skips media that’s already downloaded
* Automatically corrects non-standard extensions (e.g. `.getBlob`)


## 🛠️ Installation Instructions

### Ensure Python 3.6+ is installed

Check your version:

```bash
python3 --version
```
<!-- FYI: default for openSUSE Leap 15.6 is 3.6.15, for Leap 16.0 it's 3.13.5 -->

If it's missing or outdated:

* **Debian/Ubuntu:**
  ```bash
  sudo apt update
  sudo apt install python3 python3-venv python3-pip
  ```
* **openSUSE:**
  ```bash
  sudo zypper install python3 python3-pip python3-virtualenv
  ```

### Install the Project

It is recommended to install into a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
```

The repository includes a `setup.py` for building.
From the repository root:

```bash
pip install .
```

This uses the `setup.py` provided.


### ⚙️ Configuration

```bash
cp .env.example .env
```

Edit `.env` and fill in:

```env
MASTODON_TOKEN=your_access_token_here
MASTODON_INSTANCE=https://your.instance
MAX_BOOKMARKS=80
```

Your token **must** have at least:

* `read`
* `read:bookmarks`

Tokens can be managed at `https://your.instance/settings/applications`.

---

## 🚀 Usage


After installation, you can run the script with default config from `.env`:

```bash
mastodon-bookmarkmedia
```

Or override options directly from the command line:

```bash
mastodon-bookmarkmedia \
  --token YOUR_ACCESS_TOKEN \
  --instance https://your.instance \
  --max-bookmarks 200 \
  --media image \
  --outdir images
```

### 🔧 Options

| Option            | Description                                     | Required               | Default         |
| ----------------- | ----------------------------------------------- | ---------------------- | --------------- |
| `--token`         | Mastodon access token                           | Yes (unless in `.env`) | none            |
| `--instance`      | Mastodon instance base URL (e.g. `https://...`) | Yes (unless in `.env`) | mastodon.social |
| `--max-bookmarks` | Only include this number of newest bookmarks    | No                     | `80`            |
| `--media`         | Filter media type: `image`, `video`, `all`      | No                     | `all`           |
| `--outdir`        | Directory to save downloaded media              | No                     | `downloads`     |


### 📦 Output

Downloaded media will be saved in the `downloads/` directory (or the folder you set via `--outdir`). Filenames follow this pattern:

```
username_instance_postid[-N].ext
```

For example:

```
johndoe_mastodon-social_1094823048123.jpg
johndoe_mastodon-social_1094823048123-2.png
```

If a post includes multiple media files, suffixes like `-2`, `-3`, etc. will be appended.

Non-standard server extensions (e.g. `.getBlob`) are automatically fixed by inspecting file content.
The tool will guess a correct extension.

---

## 📝 License

This project is licensed under the **Mozilla Public License 2.0+ (MPL-2.0)**.
You are free to use, modify, and redistribute the code under the terms of this license.

---

## 🙋 FAQ

**Q:** What happens if I bookmark an old post today?
**A:** The script filters by the **post creation date**, not the bookmark date.

**Q:** What if I run the script multiple times?
**A:** Already-downloaded media is skipped automatically.

**Q:** Will this download media from *private* posts?
**A:** If you have permission to view and bookmark the post, it should work.

---

Feel free to fork or contribute to improve the script!

