Adding Client Apps to the Catalog

Want to list your app in the Compatible Client Apps catalog? This guide explains how to submit your app or update an existing entry.

Prerequisites

• Your app must support the OpenSubsonic, Subsonic, or Navidrome API
• You’ll need a GitHub account to submit a pull request
• Images must be in WebP format, max 1200px (PNG/JPEG needs to be converted)

Quick Start

1. Fork the navidrome/website repository
2. Create a folder for your app in assets/apps/ using kebab-case (e.g., my-awesome-app)
3. Add an index.yaml file with your app’s metadata
4. Add a thumbnail image and optional gallery screenshots
5. Convert (or resize) images if needed:

   npm run convert:images my-awesome-app
   

6. Validate your entry using the provided scripts:

   npm run validate:app my-awesome-app
   

7. Submit a pull request

Folder Structure

Each app has its own folder under assets/apps/:

assets/apps/
  my-app/
    index.yaml        # App metadata (required)
    thumbnail.webp    # App thumbnail (required)
    screen1.webp      # Gallery screenshot (optional)
    screen2.webp      # Gallery screenshot (optional)

Creating index.yaml

Use the template at assets/apps/_template/index.yaml as a starting point.

Required Fields

Optional Fields

Open Source vs Repository URL

The repoUrl field is used to fetch the app’s last release date. If your app has a GitHub or GitLab repository, include it for accurate “last updated” information.

The isOpenSource field controls whether the app displays an open source badge and appears in the “Open Source Only” filter:

• If repoUrl is set and isOpenSource is omitted → app is treated as open source (default)
• If repoUrl is set and isOpenSource is false → app is NOT treated as open source
• If repoUrl is not set → app is NOT treated as open source (regardless of isOpenSource)

Use isOpenSource: false when your app has a GitHub/GitLab repository for releases or issue tracking, but the source code is not publicly available under an open source license.

Supported Platforms

• android - Google Play Store
• ios - Apple App Store
• macos - macOS (optionally with Mac App Store link)
• windows - Windows
• linux - Linux
• web - Web browser
• docker - Docker container (optionally with Docker Hub link)
• other - CLI tools, other platforms

Example index.yaml

name: My Music App
url: https://example.com/my-app
repoUrl: https://github.com/example/my-app  # Optional - used for release tracking
# isOpenSource: false  # Uncomment if repo exists but source code is not public

platforms:
  android:
    store: https://play.google.com/store/apps/details?id=com.example.myapp
  ios:
    store: https://apps.apple.com/app/my-app/id123456789
  web: true
  linux: true

api: OpenSubsonic

description: A beautiful music player with offline support and gapless playback.

screenshots:
  thumbnail: thumbnail.webp
  gallery:
    - screen1.webp
    - screen2.webp

keywords:
  - dlna
  - chromecast
  - carplay
  - android auto

Image Guidelines

Thumbnail (Required)

• Max size: 1200×1200px
• Aspect ratio: Square preferred
• Format: WebP (PNG/JPEG needs to be converted)

Gallery Images (Optional)

• Max size: 1200×1200px
• Aspect ratio: Any
• Format: WebP (PNG/JPEG needs to be converted)
• File size: Keep under 500KB per image

Processing Images

If your images don’t meet the guidelines, run the conversion script:

npm run convert:images my-app

This automatically converts images to WebP format, resizes them to max 1200px, and optimizes file sizes.

Validating Your Entry

Before submitting, validate your app entry:

npm run validate:app my-app

The validation checks:

• YAML syntax and structure
• Required fields are present
• APIs are correctly specified
• Image files exist
• URLs are valid and reachable
• File sizes (warns if images > 500KB)

Updating an Existing App

To update an existing app entry:

1. Find the app folder in assets/apps/
2. Modify the index.yaml or replace images as needed
3. Run validation and submit a pull request

Questions?

If you have questions about adding your app, please open an issue on GitHub.