Metadata-Version: 2.1
Name: mastodon-bookmarkmedia
Version: 0.8.1
Summary: Download and archive media from Mastodon bookmarks
Home-page: UNKNOWN
Author: Philipp Bielefeldt
Author-email: philipp@bielefeldt.online
License: MPL-2.0
Description: # 📚 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!
        
        
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
