VibeVox — Flathub Metadata & AppStream XML Specifikáció

Linux GTM Playbook → Fázis 1 | P0 Launch Blocker

Forrás: Go-To-Market Playbook for Commercial Native Linux Applications (2026-04-08) Státusz: Kötelező — minden Flathub PR előtt teljesítendő Kapcsolódó: 08_Product.md §Flathub · 14_Launch_Playbook.md · 07_Compliance.md §OARS

1. AppStream XML kötelező elemek

1.1. Fájl neve és helye

Flatpak manifest repo:
  com.vibevox.VibeVox.metainfo.xml
  (korábban: .appdata.xml — 2024 óta deprecated, metainfo.xml a standard)

1.2. Alapstruktúra — teljes sablon

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">

  <!-- App ID: egyezzen a Flatpak manifest ID-val -->
  <id>com.vibevox.VibeVox</id>

  <!-- Metadata license: KÖTELEZŐ -->
  <metadata_license>CC0-1.0</metadata_license>

  <!-- App license -->
  <project_license>LicenseRef-proprietary</project_license>

  <!-- Teljes név -->
  <name>VibeVox</name>

  <!-- Summary: MAX 35 KARAKTER — app neve NEM ismételhető -->
  <!-- ✅ Helyes: "Privacy-first hold-to-talk dictation" (39 char — TÚLLÉPI, rövidíteni kell) -->
  <!-- ✅ Elfogadható: "Hold-to-talk voice typing for Linux" (36 char — 1-el túl) -->
  <!-- ✅ Optimális: "Privacy-first dictation for Linux" (33 char) -->
  <summary>Privacy-first dictation for Linux</summary>

  <!-- Fejlesztő neve -->
  <developer>
    <name>Joe (VibeVox)</name>
  </developer>

  <!-- Leírás: HTML-mentes plain text vagy basic markup -->
  <description>
    <p>
      VibeVox is a native, privacy-first hold-to-talk dictation application
      for Linux and Windows. Unlike ambient listening apps, VibeVox only activates the microphone
      when you press the button — ensuring your voice never leaves your device uninvited.
    </p>
    <p>Key features:</p>
    <ul>
      <li>Hold-to-talk only — mic activates exclusively on button press</li>
      <li>EU-hosted (Frankfurt) — your audio stays in Europe, GDPR SCC-compliant</li>
      <li>BYOK (Bring Your Own Key) — use your own Groq/OpenAI API key for pennies per minute</li>
      <li>CEE filler word removal — Hungarian (ööö, hát), Polish (eee, no), Czech (takže), Slovak</li>
      <li>~150MB RAM during active recording — won't compete with your IDE</li>
      <li>Literal Mode (default) — exact transcription, no AI rewriting</li>
      <li>PipeWire and PulseAudio auto-detection</li>
    </ul>
    <p>
      Designed for developers, lawyers, doctors, and knowledge workers who need precision
      dictation without surveillance risks. Native Linux integration via PySide6 —
      no Electron, no browser wrapper.
    </p>
  </description>

  <!-- OARS 1.1 — KÖTELEZŐ, hiánya = fatal linter error (ld. §3) -->
  <content_rating type="oars-1.1">
    <content_attribute id="violence-cartoon">none</content_attribute>
    <content_attribute id="violence-fantasy">none</content_attribute>
    <content_attribute id="violence-realistic">none</content_attribute>
    <content_attribute id="violence-bloodshed">none</content_attribute>
    <content_attribute id="violence-sexual">none</content_attribute>
    <content_attribute id="violence-desecration">none</content_attribute>
    <content_attribute id="violence-slavery">none</content_attribute>
    <content_attribute id="violence-worship">none</content_attribute>
    <content_attribute id="drugs-alcohol">none</content_attribute>
    <content_attribute id="drugs-narcotics">none</content_attribute>
    <content_attribute id="drugs-tobacco">none</content_attribute>
    <content_attribute id="sex-nudity">none</content_attribute>
    <content_attribute id="sex-themes">none</content_attribute>
    <content_attribute id="sex-homosexuality">none</content_attribute>
    <content_attribute id="sex-prostitution">none</content_attribute>
    <content_attribute id="sex-adultery">none</content_attribute>
    <content_attribute id="sex-appearance">none</content_attribute>
    <content_attribute id="language-profanity">none</content_attribute>
    <content_attribute id="language-humor">none</content_attribute>
    <content_attribute id="language-discrimination">none</content_attribute>
    <content_attribute id="social-chat">none</content_attribute>
    <content_attribute id="social-info">none</content_attribute>
    <content_attribute id="social-audio">none</content_attribute>
    <content_attribute id="social-location">none</content_attribute>
    <content_attribute id="social-contacts">none</content_attribute>
    <content_attribute id="money-purchasing">none</content_attribute>
    <content_attribute id="money-gambling">none</content_attribute>
  </content_rating>

  <!-- Branding colors — KÖTELEZŐ (ld. §2); pure white/black/szürke TILTOTT -->
  <!-- Electric Trust paletta: #8B7FF0 (light/hover), #6C5CE7 (Electric Violet, dark) -->
  <branding>
    <color type="primary" scheme_preference="light">#8B7FF0</color>
    <color type="primary" scheme_preference="dark">#6C5CE7</color>
  </branding>

  <!-- Kategóriák -->
  <categories>
    <category>Accessibility</category>  <!-- ELSŐDLEGES — kisebb verseny, jobb discovery -->
    <category>Utility</category>         <!-- MÁSODLAGOS -->
  </categories>

  <!-- Kulcsszavak — CEE lokalizált és EN közös -->
  <keywords>
    <keyword>dictation</keyword>
    <keyword>speech</keyword>
    <keyword>voice</keyword>
    <keyword>typing</keyword>
    <keyword>transcription</keyword>
    <keyword>privacy</keyword>
    <keyword>byok</keyword>
    <keyword>eu-hosted</keyword>
    <keyword>accessibility</keyword>
    <keyword>rsi</keyword>
    <keyword>speech-to-text</keyword>
    <keyword>voice-typing</keyword>
    <keyword xml:lang="hu">diktálás</keyword>
    <keyword xml:lang="pl">dyktowanie</keyword>
    <keyword xml:lang="cs">dikce</keyword>
    <keyword xml:lang="sk">diktovanie</keyword>
    <keyword xml:lang="cs">rozpoznávání</keyword>
  </keywords>

  <!-- URL-ek -->
  <url type="homepage">https://vibevox.app</url>
  <url type="bugtracker">https://github.com/Joe-ETS/VibeVox/issues</url>
  <url type="translate">https://github.com/Joe-ETS/VibeVox</url>

  <!-- Launchable -->
  <launchable type="desktop-id">com.vibevox.VibeVox.desktop</launchable>

  <!-- Screenshotok — ld. §2 teljes szabályrendszer -->
  <screenshots>
    <screenshot type="default">
      <caption>Hold-to-talk dictation — mic only activates on button press</caption>
      <image type="source" width="1000" height="700">
        https://vibevox.app/screenshots/main_hold_to_talk_en.png
      </image>
      <image type="source" width="2000" height="1400">
        https://vibevox.app/screenshots/main_hold_to_talk_en@2x.png
      </image>
    </screenshot>
    <screenshot>
      <caption xml:lang="hu">BYOK varázsló — saját API kulcs, 3 lépésben</caption>
      <image xml:lang="hu" type="source" width="1000" height="700">
        https://vibevox.app/screenshots/byok_wizard_hu.png
      </image>
    </screenshot>
    <screenshot>
      <caption>CEE filler word removal — ööö, hát, szóval removed automatically</caption>
      <image type="source" width="1000" height="700">
        https://vibevox.app/screenshots/filler_removal_demo_en.png
      </image>
    </screenshot>
    <screenshot>
      <caption>Flatpak native GNOME integration — dark theme, system tray</caption>
      <image type="source" width="1000" height="700">
        https://vibevox.app/screenshots/gnome_integration_dark_en.png
      </image>
    </screenshot>
    <screenshot>
      <caption>CEE localization — Hungarian, Slovak, Polish, Czech support</caption>
      <image type="source" width="1000" height="700">
        https://vibevox.app/screenshots/cee_localization_en.png
      </image>
    </screenshot>
  </screenshots>

  <!-- Releases — minden verzióhoz kötelező -->
  <releases>
    <release version="1.5.0" date="2026-04-01">
      <description>
        <p>First public Flathub release.</p>
        <ul>
          <li>PipeWire and PulseAudio auto-detection</li>
          <li>BYOK wizard — 3-step API key setup</li>
          <li>CEE filler word removal: Hungarian, Slovak, Polish, Czech</li>
          <li>Session hard cap (6 minutes) for quality assurance</li>
          <li>System tray: lock icon when inactive, mic icon when recording</li>
        </ul>
      </description>
    </release>
  </releases>

</component>

2. Screenshot szabályok — részletes specifikáció

2.1. Méretek

2.2. Drop shadow mandátum

Tiling WM probléma (i3, Sway, Hyprland):

❌ PROBLÉMA: Tiling WM-eken a screenshot tool nem renderel drop shadow-t
             → az ablak lebegő árnyék nélkül jelenik meg → "unpolished" megítélés

✅ MEGOLDÁS: Screenshotokat GNOME session alatt kell készíteni
             → GNOME Shell automatikusan rendereli az alpha-channel drop shadow-t
             → Eszköz: gnome-screenshot --window (nem fullscreen!)

2.3. Caption szabályok

2.4. BCP47 language tagging

Minden nem-angol screenshot caption-höz kötelező az xml:lang attribútum:

<!-- Helyes: -->
<caption xml:lang="hu">BYOK varázsló — saját API kulcs, 3 lépésben</caption>
<caption xml:lang="pl">Dyktowanie głosowe dla Linuksa</caption>

<!-- Hibás: -->
<caption>Magyar felirat</caption>

3. OARS 1.1 — Flathub kötelező minősítés

Ha az OARS blokk hiányzik: fatal error → az app el sem jut a manuális review fázisba.

<!-- OARS 1.1 — VibeVox teljes konfiguráció (minden elem kötelező) -->
<content_rating type="oars-1.1">
  <content_attribute id="violence-cartoon">none</content_attribute>
  <content_attribute id="social-chat">none</content_attribute>
  <content_attribute id="social-info">none</content_attribute>
  <content_attribute id="social-audio">none</content_attribute>
  <content_attribute id="social-location">none</content_attribute>
  <content_attribute id="social-contacts">none</content_attribute>
  <content_attribute id="money-purchasing">none</content_attribute>
  <content_attribute id="money-gambling">none</content_attribute>
</content_rating>

4. Branding color tag — szabályok

<branding>
  <color type="primary" scheme_preference="light">#8B7FF0</color>  <!-- Electric Violet Light — vibrant, ByteSharp uniqueness -->
  <color type="primary" scheme_preference="dark">#6C5CE7</color>   <!-- Electric Violet — brand primary -->
</branding>

Ikon szabály: Az ikon SVG/PNG fájl nem tartalmazhat beégetett drop shadow-t vagy glow-t. A drop shadow-t az OS rendereli — ha benne van az ikonban, duplán jelenik meg.

5. Domain verification — Featured státusz előfeltétele

A Flathub Featured státusz eléréséhez domain verification szükséges.

Lépések:
  1. Menj a Flathub Developer Portal-ra: flathub.org/developer
  2. Kapcsold össze a vibevox.app domaint
  3. Helyezd el a verification token-t:
     vibevox.app/.well-known/org.flathub.VerifiedApps.txt
  4. Alternatív: GitHub OAuth (ha a repo public és a developer GitHub-ja meg van adva)

6. Flatpak sandbox jogosultságok — least privilege

# com.voicetypingbyjoe.VoiceTypingByJoe.yaml (részlet)
finish-args:
  - --socket=pulseaudio         # PulseAudio mikrofon hozzáférés
  - --socket=pipewire           # PipeWire mikrofon hozzáférés (ha PipeWire natív)
  - --socket=x11                # X11 input injection (xdotool)
  - --socket=wayland            # Wayland display (ablak renderelés)
  - --share=network             # Groq API + Supabase sync
  - --talk-name=org.freedesktop.secrets  # GNOME Keyring (API kulcs tárolás)
  - --device=all                # Mikrofon periféria hozzáférés

7. appstreamcli linter — helyi futtatás (CI kötelező)

# Flathub benyújtás előtt KÖTELEZŐ: 0 hiba, 0 warning
appstreamcli validate com.vibevox.VibeVox.metainfo.xml

# Elvárt output:
# com.vibevox.VibeVox.metainfo.xml: OK

# Hibaüzenet példák és megoldásuk:
# ERROR: summary-too-long        → rövidítsd 35 karakterre
# ERROR: content-rating-missing  → add hozzá az OARS blokkot
# WARNING: no-screenshots        → adj hozzá legalább 3 screenshotot
# WARNING: tag-empty             → ellenőrizd az üres XML tageket

8. Flathub Featured státusz — eligibility checklist

Featured eligibility checklist:
  □ appstreamcli lint: 0 hiba, 0 warning
  □ OARS 1.1 blokk teljes (ld. §3)
  □ Branding color tag: light + dark scheme, vibrant hex (ld. §4)
  □ Summary: ≤35 karakter, nem ismétli az app nevet
  □ Ikon: nincs beégetett drop shadow / glow
  □ Min. 3 screenshot: GNOME session renderelt, drop shadow, BCP47 tagged
  □ Legalább 1 lokalizált screenshot (hu/pl/cs/sk)
  □ Domain verification token: vibevox.app/.well-known/org.flathub.VerifiedApps.txt
  □ Release entries: minden verzióhoz `<release>` blokk changelog-gal
  □ Launch után: Flathub developer portal figyelése (editor rating)
  □ Ha bármely editor flag jelenik meg → azonnal javítás + re-review request

9. Flathub launch szinkronizáció (Launch Playbook cross-reference)

Kapcsolódó:

• 08_Product.md §Flathub — Flathub stratégiai döntés és launch checklist
• 14_Launch_Playbook.md — D-14 Flathub PR szinkronizáció
• 07_Compliance.md §OARS — OARS compliance összefüggés