diff --git a/docs/install.md b/docs/install.md index 626997e5..71fe804f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,12 +1,12 @@ --- -title: Installation +title: Installing icon: material/download --- -# :material-download: Installation +# :material-download: Installing TagStudio provides executable [releases](https://github.com/TagStudioDev/TagStudio/releases) as well as full access to its [source code](https://github.com/TagStudioDev/TagStudio) under the [GPLv3](https://github.com/TagStudioDev/TagStudio/blob/main/LICENSE) license. @@ -17,8 +17,8 @@ To download executable builds of TagStudio, visit the [Releases](https://github. TagStudio has builds for :fontawesome-brands-windows: **Windows**, :fontawesome-brands-apple: **macOS** _(Apple Silicon & Intel)_, and :material-penguin: **Linux**. We also offer portable releases for Windows and Linux which are self-contained and easier to move around. -!!! info "Third-Party Dependencies" - You may need to install [third-party dependencies](#third-party-dependencies) such as [FFmpeg](https://ffmpeg.org/download.html) to use the full feature set of TagStudio. +!!! info "Optional Dependencies" + You may need to install [optional third-party dependencies](#optional-dependencies) such as [FFmpeg](https://ffmpeg.org/download.html) to use the full feature set of TagStudio. !!! warning ":fontawesome-brands-apple: macOS "Privacy & Security" Popup" @@ -82,6 +82,19 @@ Some external dependencies are required for TagStudio to execute. Below is a tab | [qt-multimedia](https://repology.org/project/qt) | required | | [qt-wayland](https://repology.org/project/qt) | Wayland support | + +!!! bug "Missing Linux Dependency Example" + An error message such as the following indicates that you're missing the `libxcb-cursor` or `xcb-util-cursor` library, depending on your distro: + ``` + qt.qpa.plugin: From 6.5.0, xcb-cursor0 or libxcb-cursor0 is needed to load the Qt xcb platform plugin. + qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "/tmp/_MEIayuTiW/cv2/qt/plugins" even though it was found. + This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem. + + Available platform plugins are: vnc, wayland-egl, offscreen, wayland, linuxfb, minimalegl, eglfs, minimal, vkkhrdisplay, xcb. + + Aborted (core dumped) + ``` + ### :material-nix: Nix(OS) For [Nix(OS)](https://nixos.org/), the TagStudio repository includes a [flake](https://wiki.nixos.org/wiki/Flakes) that provides some outputs such as a development shell and package. @@ -212,7 +225,9 @@ Finally, `inputs` can be used in a module to add the package to your packages li Don't forget to rebuild! -## Third-Party Dependencies +## Optional Dependencies + +Some TagStudio functionality such as multimedia thumbnails and playback, RAR archive thumbnails, and improved directory scanning performance will require installing optional third-party dependencies. Depending on your system, you may already have one or more of these installed. To check !!! tip @@ -242,21 +257,3 @@ To generate thumbnails for RAR-based files (like `.cbr`) you'll need an extracto ### ripgrep A recommended tool to improve the performance of directory scanning is [`ripgrep`](https://github.com/BurntSushi/ripgrep), a Rust-based directory walker that natively integrates with our [`.ts_ignore`](ignore.md) (`.gitignore`-style) pattern matching system for excluding files and directories. Ripgrep is already pre-installed on some Linux distributions and also available from several package managers. - -## Common Error Messages - -### Could not load the Qt platform plugin "xcb" - -If you get an error message like this one: - -``` -qt.qpa.plugin: From 6.5.0, xcb-cursor0 or libxcb-cursor0 is needed to load the Qt xcb platform plugin. -qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "/tmp/_MEIayuTiW/cv2/qt/plugins" even though it was found. -This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem. - -Available platform plugins are: vnc, wayland-egl, offscreen, wayland, linuxfb, minimalegl, eglfs, minimal, vkkhrdisplay, xcb. - -Aborted (core dumped) -``` - -Make sure you installed `libxcb-cursor` or `xcb-util-cursor`. diff --git a/docs/preview-support.md b/docs/preview-support.md index a20fe338..df64c56d 100644 --- a/docs/preview-support.md +++ b/docs/preview-support.md @@ -47,7 +47,7 @@ Images will generate thumbnails the first time they are viewed or since the last ### :material-movie-open: Videos -Video thumbnails will default to the closest viable frame from the middle of the video. Both thumbnail generation and video playback in the Preview Panel requires [FFmpeg](install.md#third-party-dependencies) installed on your system. +Video thumbnails will default to the closest viable frame from the middle of the video. Both thumbnail generation and video playback in the Preview Panel requires [FFmpeg](install.md#optional-dependencies) installed on your system. | Filetype | Extensions | Dependencies | | --------------------- | ----------------------- | :----------: | @@ -65,7 +65,7 @@ Video thumbnails will default to the closest viable frame from the middle of the ### :material-sine-wave: Audio -Audio thumbnails will default to embedded cover art (if any) and fallback to generated waveform thumbnails. Audio file playback is supported in the Preview Panel if you have [FFmpeg](install.md#third-party-dependencies) installed on your system. Audio waveforms are currently not cached. +Audio thumbnails will default to embedded cover art (if any) and fallback to generated waveform thumbnails. Audio file playback is supported in the Preview Panel if you have [FFmpeg](install.md#optional-dependencies) installed on your system. Audio waveforms are currently not cached. | Filetype | Extensions | Dependencies | | ------------------- | ------------------------ | :----------: | diff --git a/mkdocs.yml b/mkdocs.yml index 2c87f783..a56509bd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,9 +32,8 @@ extra: nav: - Home: - index.md - - Getting Started: + - Installing: - install.md - - usage.md - Developers: - developing.md - contributing.md @@ -42,6 +41,7 @@ nav: - Help: - help/ffmpeg.md - Using TagStudio: + - usage.md - libraries.md - entries.md - preview-support.md