Anemone Media Player: Linux Installation Guide
================================================

CONTENTS
  1. Quick start (run without installing)
  2. System requirements
  3. Install (create desktop shortcut + menu entry)
  4. Uninstall
  5. Distro-specific dependency notes
  6. Troubleshooting


1. QUICK START (run without installing)
---------------------------------------
Extract the tarball to any folder and run the launcher directly:

    tar -xzf anemone-linux-x86_64.tar.gz
    cd anemone/
    ./anemone

No root access is needed for this, and nothing needs setting up: the
app finds the libraries it bundles by itself.


2. SYSTEM REQUIREMENTS
-----------------------
  - x86_64 CPU (64-bit)
  - A running X11 or Wayland session (XWayland is supported)
  - VLC media player (for video/audio playback)

Anemone ships its own Qt and xcb libraries, including the whole
xcb/xkbcommon set the window system needs, so it runs on a minimal
install with no desktop environment present.  VLC is the one external
dependency you need to install yourself.


3. INSTALL (desktop shortcut + application menu entry)
-------------------------------------------------------
After extracting the tarball, run the included installer script
as your normal user (no sudo required for a per-user install):

    cd anemone/
    ./install.sh

This will:
  - Copy the application to ~/.local/share/anemone/, replacing the
    copy a previous install left there
  - Create a launcher at ~/.local/bin/anemone, so `anemone` starts it
    from a terminal
  - Register a .desktop entry so Anemone appears in your app menu
  - Add an icon to ~/.local/share/icons/hicolor/256x256/apps/

The installed copy does not use the folder you extracted, so you can
delete that folder once the installer has finished.

Log out and back in (or run `update-desktop-database`) if the menu
entry does not appear immediately.  The same goes for the `anemone`
command if ~/.local/bin was not already on your PATH: most
distributions add it at login once the folder exists.

Anemone checks for updates when it starts and shows an Update button
when there is one.  To update from a terminal instead, run:

    ~/.local/share/anemone/update.sh


4. UNINSTALL
-------------
Run the uninstaller from the installed copy:

    ~/.local/share/anemone/uninstall.sh

It removes the application, the `anemone` command, the menu entry
and the icon.  Your settings and licence in ~/Documents/Anemone are
kept.

If you only ever ran Anemone from the extracted folder (section 1),
there is nothing to uninstall: delete the folder.


5. DISTRO-SPECIFIC DEPENDENCY NOTES
-------------------------------------

Ubuntu 20.04 / 22.04 / 24.04 and Debian 11/12:
    sudo apt update
    sudo apt install vlc

Fedora 38+ / RHEL 9+ / AlmaLinux / Rocky Linux:
    sudo dnf install vlc

    If vlc is not in the default repos, enable RPM Fusion first:
    sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
    sudo dnf install vlc

Arch Linux / Manjaro:
    sudo pacman -S vlc

openSUSE Tumbleweed / Leap:
    sudo zypper install vlc

    For Leap, you may need the Packman repository:
    sudo zypper ar -cfp 90 https://ftp.gwdg.de/pub/linux/misc/packman/suse/openSUSE_Leap_$(. /etc/os-release && echo $VERSION_ID)/ packman
    sudo zypper dup --from packman --allow-vendor-change
    sudo zypper install vlc

Linux Mint:
    sudo apt update
    sudo apt install vlc

    VLC is usually pre-installed on Mint, so just check it launches.

Pop!_OS:
    sudo apt install vlc libxcb-cursor0

Raspberry Pi OS (64-bit only):
    sudo apt update
    sudo apt install vlc
    Note: performance may vary on lower-end Pi hardware.


6. TROUBLESHOOTING
-------------------
App does not start / black screen:
    Make sure VLC is installed (see section 5).
    Try running from a terminal to see any error output:
        anemone
    or, if you have not installed it, from the extracted folder:
        cd anemone/
        ./anemone

"cannot open shared object file" error:
    The app bundles libxcb-cursor.so.0 itself.  If you see a
    different missing library, install it via your package manager.

App appears in terminal but not in the application menu:
    Run:  update-desktop-database ~/.local/share/applications/
    Then log out and back in.

Wayland: window appears but controls are missing:
    Try forcing X11 mode:
        QT_QPA_PLATFORM=xcb ./anemone

For further help visit: https://www.anemoneplayer.com
