Install OpenAver on Windows or macOS

What OpenAver does and how the workflow fits together

OpenAver is specifically built around JAV metadata rather than general-purpose media management. You point it at folders containing compatible video files, NFO metadata, and artwork, and it turns those records into a searchable visual catalog. It can also query supported public metadata providers to fill missing information and prepare NFO and artwork layouts for media applications such as Jellyfin, Emby, and Kodi.

That focus is important when planning installation and remote access. Even if OpenAver does not directly publish a video file, its interface may reveal explicit covers, titles, performers, tags, studios, dates, ratings, filenames, and collection patterns. A catalog can therefore be sensitive in its own right. Use fictional or otherwise non-explicit sample records for initial testing, screenshots, demonstrations, and troubleshooting whenever possible.

OpenAver describes itself as running locally without requiring an account or cloud-hosted library. Existing files remain on storage available to your computer. Internet requests are used when the application scrapes public metadata or when you configure an optional online integration. This local operating model changes when you deliberately enable server mode or create a tunnel. Browser requests and the resulting catalog pages then travel across the relevant local network or tunnel path, even though the underlying database and media remain on your computer.

The four principal OpenAver pages

The documented user interface is organized into four main pages. Scanner handles existing collections, Showcase is the visual library browser, Search processes new items, and Insights provides collection analysis. These pages have different purposes, so choosing the right one helps prevent unintended organization operations.

Insights is not merely another cover view. It provides an analytical view of the collection and allows the displayed scope to be narrowed by selecting values such as a year, performer, or studio. The surrounding charts then update to reflect that subset. This makes Insights useful for finding metadata inconsistencies as well as exploring collection trends. An unexpected gap in a year, studio, or tag distribution may indicate incomplete imported metadata that deserves review in Scanner.

Scanning, enrichment, and organization are different operations

OpenAver states that scanning an existing source is read-only with respect to that source. It reads compatible media records, NFO files, and artwork without moving or deleting the videos. Enrichment is a separate action that can add missing NFO data, covers, or still images. The project says enrichment fills empty fields rather than overwriting populated fields by default.

Organization is the operation that can rename files, create directories, write metadata, download artwork, and move content according to your configured rules. It is initiated through the Organize action after reviewing a Search result. Treat the preview as a required checkpoint, especially when a partial identifier could match more than one title.

Prerequisites and documented platform compatibility

The packaged desktop route supports Windows 10 or Windows 11 on x64 hardware. The packaged macOS route supports Apple-silicon Macs, identified by the project as M1 or later, using an arm64 build. The current project documentation does not establish a packaged Intel Mac build.

You do not need Docker for either packaged installation. OpenAver is intended to provide a graphical installation and onboarding experience. Linux has a separate self-hosted browser-server path, but it is outside the scope of this Windows and macOS tutorial.

Prepare a small test folder before the first launch. A useful test set contains a few fictional or non-explicit sample records, at least one compatible NFO file, representative artwork, and one deliberately incomplete record. This lets you verify import and enrichment behavior without immediately processing a large or sensitive catalog.

If the production library is on a NAS, external disk, or mounted cloud-storage path, verify that your normal operating-system account can open it before starting OpenAver. Network shares can disconnect, mapped drive letters can change, and removable disks can mount under a different path. Stable paths make later scanning and scheduled operations more predictable.

Install OpenAver on Windows or macOS

This guide uses the official scripted installers because the current evidence documents their behavior and security-unblocking work. OpenAver also publishes manual ZIP archives, but the available evidence refers readers to instructions inside those archives for required operating-system security steps. That is not enough to provide a self-contained and release-independent manual procedure here, so the ZIP route is intentionally omitted. Follow the exact archive documentation if you independently choose that route.

Source-development installation is also outside this guide. It has different Python, frontend, and server-startup requirements and should not be mixed with the supported packaged desktop workflow.

Install on Windows with PowerShell

On a Windows 10 or Windows 11 x64 computer, open PowerShell in your normal user session and run the official command:

irm https://raw.githubusercontent.com/slive777/OpenAver/main/install.ps1 | iex

The documented installer downloads the latest packaged release, removes the relevant system security restriction, creates a desktop shortcut on Windows, and preserves existing settings during an upgrade. The installation interface follows the operating-system language.

Windows alternative without opening PowerShell

The OpenAver README also directs Windows users to download OpenAver-Windows-Setup.bat from the project's official release area and double-click it. This is a documented alternative installation entry point for users who do not want to launch PowerShell manually.

The available evidence does not establish that the batch file has an implementation identical to install.ps1, so do not treat the two scripts as interchangeable for auditing purposes. Obtain the batch file only from the official OpenAver repository or its release assets, inspect it if required by your security policy, and follow the prompts it displays.

Install on an Apple-silicon Mac

On an M1 or later Mac, open Terminal and run the official shell installer:

curl -fsSL https://raw.githubusercontent.com/slive777/OpenAver/main/install.sh | bash

The documented installer downloads the latest release, handles the relevant macOS security restriction, and retains settings during upgrades. The packaged macOS build is arm64, so this route should not be presented as support for an Intel Mac.

Update and rollback expectations

The official installer commands are documented to fetch the latest release and preserve settings when upgrading. Before a significant update, back up important application settings and custom library metadata, close any active remote tunnel, and record a small set of known-good library entries for post-update testing.

The supplied project evidence does not define a supported automatic rollback procedure. Do not promise that an installer can downgrade safely or that data written by a newer release will always be compatible with an older one. If an update causes a problem, stop automated organization, preserve the current data and logs, review the relevant release information, and follow project-specific recovery guidance before replacing application files.

Configure and scan the first JAV metadata library

The first launch includes onboarding that asks you to select a folder and use the Generate Webpage action. Begin with the prepared test folder rather than the full collection. If that folder is on removable or network storage, make sure it remains mounted under the same path throughout the test.

OpenAver recognizes metadata from compatible standard NFO files. It can identify artwork with the same base name as the media, -poster or -fanart suffixes, conventional names such as poster, fanart, cover, or folder, paths referenced by an NFO file, and images inside an extrafanart directory. This allows collections previously prepared by other compatible tools or media servers to be imported without scraping every record again.

OpenAver can query multiple built-in JAV metadata sources, while some sources require additional verification and an optional self-hosted Metatube integration can expand provider coverage. Provider availability and returned fields can change independently of OpenAver. One source may return identity and artwork without a plot or rating, so a partially populated record does not automatically indicate an installation failure.

Configure media-center output carefully

When preparing content for Jellyfin, Emby, or Kodi, select the relevant output mode before organizing new files. OpenAver can generate NFO and artwork naming layouts for those applications, but their artwork conventions are not identical. Test one organized sample in the intended media server before applying the same rule to an entire library.

Use read-only sources for storage that must not be changed

A source can be marked read-only when videos are stored on a NAS, cloud mount, or other location that should remain untouched. For this mode, OpenAver writes generated NFO files, covers, and stills to a separate local output folder rather than modifying the source. It can also create .strm pointer files for Jellyfin, Emby, or Kodi.

Path-replacement rules address situations where OpenAver and the playback server see the same storage through different paths. Examples include a Windows UNC share, a mapped drive, or storage mounted at different locations on Windows and Linux. Verify one generated .strm file from the playback server before generating the rest.

Verify the installation locally before remote access

A successful first launch proves only that the application can start. It does not confirm persistent settings, storage availability, correct metadata associations, browser access, or authentication. Verify these layers separately so that later networking problems are not confused with application problems.

Routine scanning, organization, analysis, and updates

Scan after external library changes

Run Scanner after adding files outside OpenAver or reconnecting storage that was previously unavailable. Scanning imports compatible records already present in the source and identifies missing pieces. Enrichment then queries metadata providers for incomplete entries. Keeping these actions separate makes it easier to understand whether a problem comes from local file recognition or an online provider.

Review Search results before organizing

Search accepts a file or folder, identifies likely title codes, queries metadata providers, and presents results for review. When a folder is dragged into Search, the documented behavior reads that folder level rather than recursively scanning a whole library. Use Scanner to add a complete collection.

Before choosing Organize, verify the identifier, title, performers, artwork, metadata source, destination, and proposed naming. The Organize action can rename the item, create a folder, write NFO data, download artwork, and move associated files. Subtitle files can move with the video, and recognized VR projection tags are retained for compatible playback software.

Use scheduled organization only after manual testing

OpenAver can designate a completed-download location and run scheduled organization approximately every 12 hours, with an option to run the process immediately. Recent release behavior uses an exact single-title lookup for scheduled organization and leaves the file in place when no exact result is found. Even with that safeguard, test manual organization first and monitor the scheduled folder until the results are consistently correct.

Use Insights to spot catalog-quality problems

Insights includes collection counts, year distributions, studio charts, performer rankings, tag visualizations, performer age distributions at release, director and series rankings, studio timelines, and performer-pair analysis. Large unexplained gaps or duplicate-looking categories can reveal inconsistent aliases, dates, studios, or tags. Correct those records before relying on the charts for broader analysis.

Update cautiously

The scripted installers are intended to obtain the latest release while retaining existing settings. Before updating, stop scheduled organization, stop any Localtonet tunnel, back up custom metadata and settings, and note the current behavior of a small test set. After updating, verify startup, source connectivity, Scanner, Showcase, Search, Insights, server mode, and one disposable organization test.

Release notes can contain changes that affect network shares, enrichment success criteria, NFO fields, or organization matching. For example, the supplied v0.15.16 evidence documents fixes for libraries at a bare network-share root, cover-only enrichment, plot and rating preservation in NFO output, unexpected data types during organization, and exact matching for scheduled organization. Check the release information relevant to the version you are actually installing rather than assuming all historical behavior applies.

Enable and verify OpenAver server mode

Server mode makes the OpenAver browser interface available to another device on the same Wi-Fi or local network. The project documents password protection for this mode and recommends returning to standalone mode when network access is no longer needed.

This is the first point where the interface leaves the single-computer boundary. OpenAver may still store the library locally, but another device can request catalog pages across the LAN. If you later add Localtonet, those browser requests can travel through the Localtonet relay path to the OpenAver service.

Verify the AI API separately

OpenAver provides a capabilities manifest for AI integrations. The project documents the request in this form:

curl http://localhost:<port>/api/capabilities

Replace <port> with the value displayed in Settings under AI API. Run this verification on the OpenAver computer first. The documentation establishes that the port is shown in Settings, but the supplied evidence does not establish that users can configure it.

The AI API is not the same as the human-facing library browser. It can expose operational capabilities intended for compatible AI tools, so do not tunnel it merely because it uses HTTP. Keep it local unless a specific integration requires remote access and you have separately evaluated its authentication, authorization, and available operations.

Expose the verified browser interface with Localtonet

After the server-mode address works from another local device, you can create a Localtonet HTTP tunnel to that browser service. Our client establishes an outbound connection to a Localtonet relay server and provides a public URL. This avoids inbound router port forwarding, firewall changes for internet ingress, VPN setup, and the need for a public IP address.

Run the Localtonet client on the OpenAver computer when practical. If you run it elsewhere, that device must be able to reach the exact OpenAver host and port over the LAN. A tunnel forwards traffic to a target that already works. It cannot repair an unavailable share, disabled server mode, incorrect application port, or local firewall rule that blocks the client device.

See our HTTP tunnel documentation when completing the current dashboard form. In particular, use the current documentation for custom-domain DNS requirements rather than assuming records from an older configuration.

When a remote user opens the public URL, requests travel from that device to the Localtonet relay and through the outbound client connection to OpenAver. The returned pages can include catalog titles, tags, performer information, analysis charts, and potentially explicit artwork. This traffic path is intentionally created by the tunnel and is different from OpenAver's default local-only operation.

Protect a sensitive JAV metadata catalog

Remote access should be opt-in, limited, and easy to disable. A public URL changes the risk profile even when the application and media storage remain on your own computer. Review what the interface exposes and assume that titles, artwork, performer data, tags, filenames, collection statistics, and personal categorization may be sensitive.

Test the public URL from an unauthenticated private window and from a network outside your LAN. Existing browser cookies can hide the login flow and create the false impression that an interface is publicly open or properly protected. Verify both a rejected unauthenticated request and a successful authenticated session.

Do not share the public address more broadly than necessary. A difficult-to-guess subdomain is not authentication. If your workflow requires continuous access, periodically verify the OpenAver password behavior, review which interface is exposed, and confirm that the tunnel still targets the browser service rather than an API or obsolete port.

Troubleshooting installation, scanning, server mode, and tunneling

OpenAver does not launch after installation

Confirm that the machine matches the documented packaged target. Windows must be Windows 10 or 11 on x64 hardware. macOS must use Apple silicon for the documented arm64 package. Review the installer's terminal output and check whether endpoint-security software quarantined the application. Do not apply unrelated security-bypass commands from third-party posts.

The installer command is blocked by policy

Many managed environments prohibit directly piping downloaded scripts into an interpreter. Review or download the official script according to organizational policy, or use the official Windows setup batch file where permitted. If neither route is allowed, ask the administrator to review the project rather than weakening device-wide execution controls.

A library folder is unreachable

Open the source directly under the same operating-system account running OpenAver. Reconnect external storage, remount the NAS share, and confirm that the path has not changed. On Windows, a mapped drive may be unavailable in a different login context, while a UNC path may require an authenticated session. OpenAver's status information can identify a disconnected library.

NFO files or artwork are not imported

Test one simplified folder. Place the media, compatible NFO file, and representative image together, then compare the names with the recognized patterns. Check matching base names, -poster and -fanart suffixes, conventional artwork names, NFO-referenced paths, and the extrafanart directory. This separates naming problems from parser or permission problems.

Enrichment leaves some fields empty

Metadata providers expose different fields. Some may return a title, identity data, and artwork without a plot or rating. Confirm that the correct record was matched and preserve accurate existing data. Repeatedly scraping a record from different sources can create inconsistencies even when each individual request succeeds.

Search identifies the wrong title

Do not choose Organize. Refine the identifier or select a different result and inspect the complete preview. Verify cover art, performers, studio, tags, and destination. Scheduled organization uses exact lookup behavior in the supplied current release evidence, but manual review remains important for ambiguous filenames.

Insights contains unexpected categories or gaps

Compare the affected records in Showcase and inspect their NFO metadata. Different spellings, aliases, missing dates, or inconsistent studio and tag values can split what should be a single category. Correct the underlying records, rescan as required, and then recheck the charts.

The interface works on the host but not another local device

Confirm that OpenAver is in server mode and use the exact address it displays. Ensure both devices are on the same trusted network. Guest Wi-Fi often blocks communication between clients even when both devices have internet access. Review the operating-system firewall prompt and allow the application only on the intended trusted network profile.

The Localtonet public URL cannot connect

Work through the chain in order:

• Confirm that OpenAver is running in server mode.
• Open the displayed browser URL from the device running the Localtonet client.
• Compare the tunnel's local target host and port with the current OpenAver address.
• Confirm that the intended Localtonet device is connected.
• Confirm that the tunnel was started rather than only created.
• Test the public URL from an outside network after changing one variable at a time.

If OpenAver displays a different address after an update or settings change, update the tunnel target accordingly. Do not substitute the port shown under AI API for the browser port.

The public page opens without the expected password

Stop the tunnel immediately. Return to OpenAver Settings, confirm server-mode password protection, and test again from a fresh private browser window on the LAN. Restart the tunnel only after an unauthenticated session is challenged as expected.

The AI capabilities request fails

Use the port displayed specifically under Settings, then AI API, and run the request from the OpenAver host first. Do not assume that the browser server and AI API use the same port. A failed capabilities request does not necessarily indicate a Scanner, Showcase, Search, Insights, or browser server problem.

Frequently asked questions