Pengaturan Linux

Snipset berjalan di Linux lewat tumpukan desktop yang sama seperti di Windows dan macOS, tetapi tumpukan itu membuat beberapa asumsi yang perlu kamu penuhi sendiri: GTK dan WebKitGTK untuk antarmuka, GStreamer untuk audio, serta helper platform untuk injeksi teks dan deteksi jendela aktif. Halaman ini membahas apa yang perlu dipasang dan cara mengonfigurasi pengetikan, pintasan global, overlay, dan suara di Wayland maupun X11.

Panduan di bawah berlaku lintas distribusi. Nama paket mencantumkan Arch lebih dulu, dengan padanan Debian dan Ubuntu di dalam tanda kurung.

Paket yang Diperlukan

# Arch
sudo pacman -S webkit2gtk-4.1 xdotool wl-clipboard \
  gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav \
  gst-plugin-pipewire xorg-xprop

# Debian / Ubuntu
sudo apt install libwebkit2gtk-4.1-0 xdotool wl-clipboard \
  gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly gstreamer1.0-libav x11-utils

Pemisahan GStreamer bukan sekadar kosmetik, dan di Arch tidak ada jalur otomatis ke dalamnya. webkit2gtk-4.1 hanya bergantung pada pustaka bersama GStreamer, dan mencantumkan set plugin sebagai opsional. Jadi, pemasangan biasa webkit2gtk-4.1 tidak menarik satu pun elemen GStreamer.

Dua set penting, karena dua alasan berbeda:

• gst-plugins-good menyediakan autoaudiosink. Tanpanya, pemutaran suara gagal dengan Could not open resource for writing.
• gst-plugins-base menyediakan decoder untuk efek suara bawaan aplikasi (oggdemux dan vorbisdec). Tanpanya, Snipset tetap mulai dan jendelanya bekerja, tetapi efek suaranya tidak berbunyi sama sekali.

Set sisanya (gst-plugins-bad, gst-plugins-ugly, gst-libav) mencakup codec ucapan. Di Debian dan Ubuntu, paket plugin good bergantung pada plugin base dan paket WebKitGTK menarik keduanya, sehingga baris apt di atas tetap bekerja meskipun tidak menyebut set base secara eksplisit.

Pengguna AppImage

AppImage membundel kerangka media. Ia menyertakan lima set plugin yang sama seperti daftar di atas, jadi kamu tidak perlu memasang paket GStreamer dari bagian sebelumnya pada host yang hanya menjalankan AppImage. Itulah gunanya bundel: host polos langsung mendapat suara yang bekerja tanpa perlu menemukan bahwa webkit2gtk-4.1 melewatkan set plugin.

Bundel hanya mencakup GStreamer dan tidak yang lain. Host tetap memerlukan:

• Output audio yang bekerja. Elemen yang dibundel berakhir di autoaudiosink; sink-nya sendiri adalah PulseAudio atau PipeWire di host, dan AppImage tidak bisa membawa server suara.
• speech-dispatcher dan espeak-ng untuk dropdown Voice Profile dan text to speech sungguhan. Lihat Ucapan ke Teks dan Teks ke Ucapan di bawah.
• ydotool di Wayland untuk injeksi tombol, yang tidak berkaitan dengan audio.

Jika efek suara senyap pada host AppImage, periksa registri GStreamer host itu sendiri sebelum mencurigai bundel:

gst-inspect-1.0 oggdemux vorbisdec autoaudiosink

Ini mencetak satu baris per elemen yang bisa dilihatnya. Elemen yang hilang berarti host tidak punya plugin, yang layak dilaporkan, karena AppImage polos tidak punya cara mengimpor plugin host saat berjalan.

Ekspansi Pengetikan di Wayland (ydotool)

X11 tidak butuh tambahan: xdotool sudah cukup. Di Wayland, injeksi tombol melewati ydotool, yang butuh daemon berjalan dan izin membuka /dev/uinput.

# Arch
sudo pacman -S ydotool
# Debian / Ubuntu
sudo apt install ydotool

sudo usermod -aG input "$USER"    # lalu reboot penuh (login ulang tidak cukup)

Jalankan daemon sebagai layanan user di ~/.config/systemd/user/ydotoold.service:

[Unit]
Description=ydotool daemon for Snipset key injection
After=default.target

[Service]
ExecStart=/usr/bin/ydotoold
Restart=on-failure

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now ydotoold
ls /run/user/$(id -u)/.ydotool_socket   # harus ada

Catatan:

• Klien mencari socket lewat $YDOTOOL_SOCKET, jika tidak ada lewat $XDG_RUNTIME_DIR/.ydotool_socket. File socket basi tanpa daemon hidup di belakangnya gagal dengan cara yang sama seperti socket yang hilang.
• Jika tidak ada daemon yang bisa dihubungi, Snipset jatuh ke injektor uinput bawaannya (yang tetap butuh grup input) alih-alih gagal diam-diam.
• Daemon tidak perlu root. Jangan jalankan ydotoold dengan sudo.

Pintasan Global di Wayland (Portal)

Di Wayland, pintasan diikat lewat portal XDG GlobalShortcuts, dan compositor (misalnya KDE Plasma) menampilkan dialog persetujuan saat peluncuran pertama dan setelah setiap perubahan pintasan di Pengaturan.

Memeriksa Pintasan yang Aktif

Portal menjawab pengikatan dengan subset pintasan yang diminta, sehingga sebuah pintasan bisa kembali tanpa tombol terpasang lalu tidak melakukan apa pun saat kamu menekannya. Buka Settings, lalu Shortcuts, dan baca daftar Shortcut Status: daftar ini menampilkan pandangan compositor sendiri atas setiap pintasan, menandai masing-masing Active atau Not active, dan menunjukkan pemicu yang benar-benar ditetapkan.

Pintasan bertanda Not active menawarkan aksi Fix inactive shortcuts, yang membuka permukaan konfigurasi portal itu sendiri. Berikan pintasan di sana dan daftar status langsung diperbarui, tanpa perlu memulai ulang Snipset.

Daftar status hanya muncul pada sesi yang mengikat lewat portal. Di X11 dan Windows, pintasan didaftarkan langsung, jadi tidak ada yang perlu dilaporkan.

Menjaga Snipset dan KDE Tetap Selaras

Snipset menyimpan setiap pintasan di preferensinya sendiri, dan KDE Plasma menyimpan pintasan yang sama di registri pintasan globalnya sendiri. Snipset menjangkau registri itu lewat portal dan, di KDE Plasma, lewat kglobalaccel, sehingga kedua sisi tetap selaras secara otomatis:

• Diubah di KDE: selagi Snipset berjalan, tombol yang diubah di Pengaturan Sistem KDE langsung berfungsi dan daftar Shortcut Status diperbarui. Perubahan di Snipset untuk pintasan itu yang masih menunggu sampai ke KDE dibuang, jadi pilihan KDE yang menang. Nilai yang tersimpan di Pengaturan Snipset, formulir pengaturan yang sedang terbuka, dan baris log was changed outside Snipset menyusul pada sesi portal berikutnya, yang dimulai saat peluncuran atau saat pintasan berikutnya disimpan.
• Diubah di Snipset: di KDE Plasma (sejak linux 0.6.876), menyimpan memasang tombol baru di desktop lewat kglobalaccel lalu membacanya kembali untuk memastikan. Ini mencakup setiap pintasan yang diikat Snipset lewat portal. Tombol yang sudah dipakai oleh aksi lain tidak dipindahkan, dan log menyebutkannya: portal: could not move '<id>' to <key> on the desktop: the key is already taken by <holder>. Desktop lain tetap mengandalkan dialog portal.

Pintasan tanpa pengikatan KDE langsung ditangani menurut statusnya. Kombinasi yang sudah dimiliki KDE bersifat otoritatif dan Snipset mengikutinya. Jika KDE melaporkan tidak ada pengikatan dan kombinasi tersimpan diketahui ditolak secara struktural, Snipset boleh memulihkan default aman untuk slot itu. Jika kombinasi tersimpan selain itu portabel, Snipset mempertahankannya dan melaporkan pintasan itu sebagai tidak aktif alih-alih mengubahnya diam-diam.

Mengapa Pintasan Bisa Ditolak

Dua situasi berbeda sama-sama terlihat seperti penolakan di log, dan keduanya butuh perbaikan yang berbeda:

Situasi	Apa yang terlihat	Apa yang harus dilakukan
Lingkungan desktop tidak akan merepresentasikan kombinasi itu, misalnya Ctrl telanjang plus tanda baca, Ctrl plus digit, atau Super plus tanda baca.	Log: this desktop environment does not grant that combination.	Tidak ada yang perlu dilakukan. Setelah portal melaporkan tidak ada pengikatan langsung, Snipset boleh memulihkan default slot. Pilih kombinasi lain jika kamu mau.
Aplikasi lain sudah memegang kombinasi itu.	Log: the compositor declined this binding, most likely because another app already holds it.	Pilih kombinasi lain.
Dua pintasan Snipset berbagi satu kombinasi.	Pengaturan menampilkan tabrakan yang menyebut kedua slot.	Hanya yang pertama bisa menyala. Ubah salah satunya.

Build lama melaporkan setiap kasus sebagai pengikatan yang dibersihkan atau ditolak dan memintamu mengaktifkannya kembali di Pengaturan, yang tidak akan berhasil, karena menyimpan ulang hanya menampilkan dialog yang sama dan compositor menolak lagi. Pesan di atas menyebut penyebab sebenarnya dan perbaikan yang berhasil.

Meluncurkan Aplikasi

Luncurkan aplikasi dari ikon desktop atau entri autostart yang sudah ada. Jangan meluncurkannya sebagai binary telanjang dari terminal. Portal mengidentifikasi aplikasi dari scope systemd dan asosiasi desktop-file, jadi peluncuran dari terminal bisa mewarisi identitas aplikasi terminal dan menaruh pintasan Snipset di bawah terminal. Gejala peluncuran yang salah identitas adalah pengikatan di bawah aplikasi yang salah, pengikatan yang tidak pernah menempel, atau galat app id.

Di KDE Plasma 6, kioclient exec <desktop-id> bukan cara meluncurkan aplikasi (ia mengurai argumennya sebagai URL) dan kstart --application tidak memulainya. Gunakan systemd-run --user --scope dengan nama unit milik aplikasi sendiri, atau klik ikon launcher.

Portal mencakup delapan menu, toggle jendela utama, shorthand pintar, antrean tempel, pembuatan kata sandi, bypass, setiap hotkey per-cuplikan, dan keempat pintasan suara. Dua kekhususan Wayland berlaku:

• Dictate, Translate, dan Ask Anything bersifat toggle (tekan untuk mulai, tekan lagi untuk berhenti): portal tidak mengirim event key-release, jadi push-to-talk dan semantik hold tidak tersedia di sana. Read Aloud membacakan isi clipboard setiap kali ditekan, sama seperti di X11.
• Default bawaan dipilih agar mengikat di KDE. Jika instalasi lama masih memegang kombinasi yang KDE tolak, Snipset menerapkan fallback hanya setelah portal melaporkan tidak ada pengikatan langsung. Pengikatan KDE yang valid tidak pernah digantikan oleh pemulihan ini.

Di X11, pintasan didaftarkan langsung, dan konflik dengan aplikasi lain dilaporkan dengan cara yang sama.

Overlay dan Kebijakan Rendering WebKit

Overlay Snipset, termasuk overlay perekaman ucapan dan Magic Menu, adalah jendela transparan always-on-top. Jika tidak satu pun pernah muncul, periksa baris kebijakan lingkungan WebKit di log startup. Pada sesi Wayland Snipset menetapkan dua variabel dan sengaja tidak menetapkan dua variabel lain:

Variabel	Wayland	X11	Alasan
WEBKIT_DMABUF_RENDERER_FORCE_SHM	set	not set	Menjauhkan DMABUF perangkat keras dari jalur render (crash WebKitWebProcess pada sebagian tumpukan Intel dan Mesa) dan tetap menampilkan frame utuh.
WEBKIT_DISABLE_DMABUF_RENDERER	not set	set	Pada jendela transparan, hanya persegi panjang yang berubah yang dilukis: overlay ucapan menampilkan titik rekam, gelombang suara, dan transkrip tanpa kartunya.
LIBGL_ALWAYS_SOFTWARE	set	set	Memaksa GL perangkat lunak pada tumpukan yang sama.
WEBKIT_DISABLE_COMPOSITING_MODE	not set	set	Menonaktifkan compositing terakselerasi membuat compositor tanpa permukaan untuk dipetakan bagi jendela transparan, sehingga tidak ada overlay yang menjadi terlihat.

Gejala WEBKIT_DISABLE_DMABUF_RENDERER aktif di Wayland (peluncur atau profil shell yang mengekspornya menimpa kebijakan, dan FORCE_SHM tidak membantu selama variabel itu ada):

• Overlay ucapan muncul, tetapi hanya berupa potongan: kotak kecil berisi titik rekam dan ikon mikrofon, batang gelombang suara, dan baris transkrip. Latar kartu, border, teks header, dan tombol hilang.
• Potongan mana yang terlihat berubah dari satu dikte ke dikte berikutnya.
• Periksa dengan tr '\0' '\n' < /proc/$(pgrep -o snipset-desktop)/environ | rg WEBKIT lalu hapus variabel itu dari baris Exec=env ... di peluncurmu.

Gejala override compositing aktif di Wayland:

• Overlay ucapan tidak pernah muncul, meskipun perekaman audio dan notifikasi tray keduanya bekerja. Audio tidak butuh jendela terpetakan, jadi overlay-lah yang gagal.
• Magic Menu dan semua overlay lain berperilaku sama, jadi ini bukan kerusakan khusus ucapan.
• Diagnostik overlay mencatat visible=false untuk setiap percobaan, dan tidak ada percobaan yang melaporkan visible=true.

Kamu bisa menimpa kebijakan itu: ekspor sendiri variabel yang dikelola dan Snipset tidak akan mengusiknya, apa pun nilainya.

# Pertahankan override compositing hanya jika mesin memang membutuhkannya,
# dan terima bahwa overlay tidak akan terpetakan di sana.
WEBKIT_DISABLE_COMPOSITING_MODE=1 snipset-desktop

Risiko sisa, dinyatakan terus terang: mesin yang WebKitGTK-nya benar-benar crash tanpa override compositing akan mengalami crash itu lagi di Wayland. Mitigasi crash dipertahankan lewat transport shared-memory di Wayland, bersama GL perangkat lunak, justru untuk mengurangi risiko itu, dan baris log startup memberitahumu mitigasi mana yang diterapkan. Tidak ada pengaturan global yang benar untuk setiap mesin, itulah sebabnya keputusan ini dicatat alih-alih disembunyikan.

Helper Opsional

Alat	Efek saat terpasang
xorg-xprop (x11-utils)	Deteksi aplikasi dan judul jendela aktif di X11: mengaktifkan whitelist dan blacklist cuplikan per-aplikasi, erase sadar terminal, dan pengecualian judul incognito.
kdotool	Deteksi jendela aktif yang sama di KDE Wayland. Tanpanya, atau di compositor Wayland lain, aplikasi jendela aktif tidak diketahui: cuplikan yang di-whitelist tidak pernah diperluas dan blacklist tidak pernah cocok.

Memasang helper itu perlu tetapi tidak cukup. Dengan kdotool, atau xprop di X11, tracker mencatat nama aplikasi aktif di Linux, dan sebagian besar angka lainnya tetap nol.

Keterbatasan Tracker Linux

Jalur penangkapan Linux sengaja dikurangi dibanding Windows:

• Tidak ada sampel kepadatan input dan tidak ada referensi screenshot yang pernah mencapai database, jadi screenshot tidak pernah dikumpulkan.
• Tanpa hash screenshot, antrean pemrosesan tidak pernah terisi dan pass sesi turunan berhenti lebih awal, meninggalkan sesi turunan kosong.
• Event input, durasi terlacak, dan durasi fokus semuanya diturunkan dari timeline kepadatan input, yang kosong di Linux, jadi ketiganya terbaca nol.
• Peralihan konteks dihitung dari sesi turunan, jadi hitungan itu juga nol.
• Kredit pengalaman waktu fokus tracker tidak terjangkau di Linux. Pengalaman dasar untuk hari terlacak tetap berlaku.
• URL browser dan judul file aktif tidak tersedia, jadi jenis konteks domain dan judul file tetap kosong di setiap mesin Linux, apa pun helper yang dipasang. Hanya konteks aplikasi yang terisi.

Deteksi jendela aktif itu sendiri tetap bergantung pada helper, dan dua display server memilih alat berbeda: Wayland butuh kdotool, X11 butuh xprop. Pada sesi Wayland, xprop tidak pernah dipakai bahkan saat terpasang.

Ucapan ke Teks dan Teks ke Ucapan

• Pintasan ucapan diikat lewat portal seperti pintasan lain, dan di Wayland pengikatan suara bersifat toggle, kecuali Read Aloud, yang membacakan clipboard setiap kali ditekan.
• Dikte jatuh ke model Whisper lokal yang dibundel setiap kali kredensial Gemini tidak ada. Kamu bisa menaruh model kustom tanpa memasang ulang. Variabel lingkungan SNIPSET_ESPEAK_BIN menimpa jalur binary ucapan.
• Mikrofon ditangkap secara native lewat ALSA atau PipeWire, dengan pengaturan boost gain mic ucapan diterapkan. WebKitGTK menolak getUserMedia, jadi jalur browser tidak pernah bisa mengirim sampel atau mengukur level. Test-Mic mengukur lewat backend tanpa dialog izin. Buffer native kosong tetap kosong dan tidak pernah diganti dengan audio sintetis.
• Text to speech lisan sungguhan butuh espeak-ng:

# Arch
sudo pacman -S espeak-ng
# Debian / Ubuntu
sudo apt install espeak-ng

Tanpanya, aplikasi memutar nada placeholder sintetis alih-alih ucapan.

• Dropdown Voice Profile adalah jalur terpisah: ia mendaftar suara yang dilaporkan WebView itu sendiri, dan di Linux WebKitGTK meminta daftar itu dari speech-dispatcher. Voice Profile yang kosong karena itu berarti lapisan itu hilang, bukan bahwa Snipset gagal. Pasang keduanya dan periksa sebelum men-debug hal lain:

# Arch
sudo pacman -S speech-dispatcher espeak-ng
# Debian / Ubuntu
sudo apt install speech-dispatcher espeak-ng

Pastikan lapisan itu bekerja dengan spd-say "Hello", lalu mulai ulang Snipset. espeak-ng adalah synthesizer formant dan sengaja terdengar robotik, jadi anggap ini fallback offline yang bekerja, bukan suara natural.

Keterbatasan Wayland yang Diketahui

• Tidak ada API global "jendela mana yang fokus" di Wayland. Snipset memakai helper di atas bila tersedia dan menurun dengan anggun jika tidak: ia tidak pernah crash dan tidak pernah menyuntik ke tempat yang salah.
• Variabel #{browser_url} dikembalikan dari clipboard saat isinya URL http, https, atau file. Membaca address bar penuh butuh Windows UI Automation dan tidak ada padanan Linux.
• ydotool dan wl-clipboard menyediakan injeksi teks dan integrasi clipboard di Wayland. Keduanya direkomendasikan oleh paket Linux.
• Jika jendela menampilkan galat Could not connect to localhost, kamu menjalankan build yang lebih lama dari perbaikan custom-protocol. Perbarui aplikasi.