## About the Name
_Kopuz_, eski bir Türk telli çalgısıdır ve genellikle birçok Orta Asya
lavtasının atası olarak kabul edilir. Geleneksel olarak bards ve şamanlar
tarafından kullanılırdı.
Kırgız _komuz_'u aynı enstrüman olmasa da muhtemelen _kopuz_'un bir soyundan
gelmektedir. Kazak _kobyz_'ı da mızrapla çalınmak yerine yayla çalınmasına
rağmen ilişkilidir. Buna karşılık, Tuvan/Yakut _xomus_ (jaw harp) ise benzer
isme rağmen tamamen ilgisizdir.
Türk efsanelerinde _kopuz_, mitolojik olmaktan ziyade efsanevi bir ozan olan
Dede Korkut ile ilişkilendirilir.
## Overview
Kopuz; ses dosyaları için yerel dizinlerinizi taramanıza, Jellyfin veya Subsonic
(Navidrome vb.) sunucunuzdan stream etmenize veya **YouTube Music** ya da
**SoundCloud**'u bir streaming backend'i olarak bağlamanıza olanak tanır, her
şeyi otomatik olarak göz atılabilir bir kütüphanede düzenler. Sanatçılara,
albümlere, türlere göre gezinebilir veya özel playlist'lerinizi
keşfedebilirsiniz. Uygulama, Rust'ın gücünü kullanarak performans ve desktop
integration için oluşturulmuştur.
Ayarlarınız, taranan kütüphane, playlist'ler ve favoriler yerel bir **SQLite**
veritabanında (`kopuz.db`) saklanır; arayüz bunu canlı olarak okur, böylece
değişiklikler anında görünür. Her medya kaynağı kendi kimlik bilgilerini ve
kendi favorilerini taşır.
## Features
[jellyfin-plugin-listenbrainz]: https://github.com/lyarenei/jellyfin-plugin-listenbrainz
- **Theming**: Görsel görünümü özelleştirmek için dinamik theming desteği
içerir. Ayrıca tam renk değişkeni kontrolü ile sıfırdan kendi custom
theme'inizi oluşturabilirsiniz.
- **Native Integration**: Linux (MPRIS), macOS (Now Playing / Remote Command
Center) ve Windows (System Media Transport Controls) üzerindeki sistem medya
kontrolleri ile entegre olur.
- **Mini-Player**: Daha küçük bir now-playing görünümü için bottom bar'dan açıp
kapatabileceğiniz kompakt bir oynatıcı katmanı.
- **Minimize to Tray**: Çıkmak yerine isteğe bağlı olarak sistem tepsisi
simgesine kapatın, böylece oynatma arka planda çalışmaya devam eder.
**Settings** içinden açıp kapatın. Linux'ta appindicator kütüphanesi gerekir
(bkz. Installation notları).
- **Discord RPC**: Gömülü RPC dahildir!!!
- **Multiple Backends**: Jellyfin veya Subsonic uyumlu sunucunuzdan (Navidrome
works great) stream edin, YouTube Music ya da SoundCloud'u bağlayın veya
sadece yerel bir klasörü gösterin. İstediğiniz gibi karıştırıp eşleştirin. Her
kaynak tek bir `MediaSource` katmanı üzerinden sunulur ve arayüz, her servise
özel davranışı sabit kodlamak yerine kaynağın yeteneklerine (arama, indirme,
radyo, discover, favori senkronizasyonu vb.) göre uyum sağlar.
- **YouTube Music**: Spotify tarzı bir **Discover** sayfası (önerilen şarkılar,
playlist'ler, albümler, sanatçılar ve ruh halleri), zengin **artist profiles**
(banner, en popüler şarkılar, albümler, single'lar, benzer sanatçılar),
albüm/playlist tarama ve **mix radyo** ("start radio" from any track) içeren
tam bir streaming backend'i. Kütüphaneniz, Beğenilen Müzikleriniz ve
playlist'leriniz için hesabınızla giriş yapın - veya herkese açık parçaları
aramak, göz atmak ve oynatmak için **anonymously** (no sign-in) çalıştırın.
Bkz. [YouTube Music Setup](#youtube-music-setup).
- **SoundCloud**: Arama, parça oynatma (progressive MP3 ve Go+ AAC/HLS),
**Beğenilen parçalarınız** favori olarak, salt okunur playlist'ler ve
like/unlike içeren streaming backend'i. İzole bir profilde tek seferlik
tarayıcı girişiyle eklenir. Bkz. [SoundCloud Setup](#soundcloud-setup).
- **Lyrics Support**: Müziğinizi takip etmek için auto-scrolling özelliğiyle
birlikte gerçek zamanlı senkronize ve düz şarkı sözlerinin keyfini çıkarın.
- **Favorites**: Parçaları yerel olarak yıldızlayın veya favorileri
Jellyfin/Subsonic sunucunuzla senkronize edin.
- **Playlists**: Kendi playlist'lerinizi oluşturun ve yönetin, tek tek parçaları
veya tüm albümleri tek seferde ekleyin ve playlist'leri sunucunuzla senkronize
edin.
- **Genre Browsing**: Hem yerel hem de sunucu müzikleri için kütüphanenizi türe
göre tarayın.
- **File-Type Badges**: Yerel parçalar, parça satırlarında küçük bir format
rozeti (MP3, FLAC, WAV vb.) gösterir; böylece kaynak formatı bir bakışta
görürsünüz.
- **Search**: Sanatçılar, albümler ve parçalar arasında gerçek zamanlı
sonuçlarla arama yapın.
- **Listening Logs**: En çok neyi dinlediğinizi görebilmeniz için çalma
sayılarını yerel olarak takip eder.
- **Scrobbling**: ListenBrainz'e scrobble edin. Birden fazla istemci
kullanıyorsanız, Jellyfin kullanıcıları için [jellyfin-plugin-listenbrainz]
önerilir.
- **Language Support**: UI dili İngilizce, Rusça, Almanca, Fransızca,
İspanyolca, Türkçe, Ukraynaca, Lehçe, Arapça, Yunanca, İbranice, Macarca,
Endonezce, Japonca, Korece, Romence, Brezilya Portekizcesi, Toki Pona ve
Basitleştirilmiş Çince dillerinde mevcuttur ve yeni diller eklemek için
kolaylaştırılmış bir deneyim sunar.
- **High Performance**: Yoğun background processing ve optimize edilmiş bir
kütüphane tarayıcısı, uygulamanın anında açılmasını, sorunsuz çalışmasını ve
daha önce indekslenmiş dosyaları hızla atlamasını sağlar.
- **Auto-Cleanup**: Yeniden tarama yaparken eksik veya silinmiş parçaları
kütüphanenizden otomatik olarak kaldırır.
- **Smooth Navigation**: Farklı görünümlere ve sayfalara göz atarken scroll
pozisyonlarının düzgün bir şekilde sıfırlandığı cilalı bir arayüzün keyfini
çıkarın.
- **Reduce Animations**: Daha sakin bir UI tercih ediyorsanız hareket
efektlerini hafifletmek için erişilebilirlik ayarı.
- **Equalizer**: Sesinize ince ayar yapmak için hazır ayarlar (presets) ve özel
ayarlara sahip dahili 5 bantlı ekolayzır.
- **Crossfade**: Native masaüstü derlemelerinde şarkılar arasında daha yumuşak
otomatik oynatmak için parça geçişlerini harmanlayın. Tarayıcı oynatımı şu
anda normal parça geçişini kullanır.
- **Channel Mode**: Switch between `Stereo`, `Mono`, `Left only`, `Right only`,
ve `Swap L/R` çıkış modları.
- **yt-dlp Integration**: yt-dlp aracılığıyla doğrudan YouTube ve desteklenen
diğer sitelerden ses indirin. Çıkış formatınızı seçin (Best Audio, MP3, FLAC,
WAV veya MP4 video). yt-dlp kayıpsız bir kaynaktan kod çözmek yerine kayıplı
sesi yeniden paketlediği (remux) için FLAC önerilmez. SponsorBlock, bölüm
bölme (chapter splitting), çerezler (cookies), hız sınırlama (rate limiting)
ve daha fazlasını destekler. Sisteminizde `yt-dlp` kurulu olmasını gerektirir.
- **Metadata Settings**: Ayarlar'daki özel bir Metadata bölümü, sanatçı
resimlerinin nasıl alınacağını kontrol etmenizi sağlar. **Album Cover**
(sanatçı fotoğrafı olarak ilk albüm kapağını kullanır, varsayılan) veya
**Artist Photo** (gerçek sanatçı resimlerini doğrudan Jellyfin veya Subsonic
sunucunuzdan çeker) seçeneklerinden birini seçin. Artist Photo moduna
geçildiğinde, Sanatçılar sayfasını açtığınız anda resimler arka planda
sunucudan çekilir. Sunucunuzda bir sanatçının özel fotoğrafı yoksa, hiçbir
şeyin boş görünmemesi için fallback olarak ilk albüm kapağı kullanılır.
## Installation
### Cargo (crates.io)
Install directly with Cargo:
```bash
cargo install kopuz
```
### NixOS / Nix
**Run directly without installing:**
```bash
nix run github:temidaradev/kopuz
```
**Install to your profile:**
```bash
nix profile add github:temidaradev/kopuz
```
**On NixOS, using the flake:**
> [!TIP]
> Bu yöntem, Kopuz'u simgesi ve `.desktop` girişi olan düzgün bir sistem
> uygulaması olarak kurduğu için `nix profile` yerine önerilir.
Kopuz'u `flake.nix` girdilerinize (inputs) ekleyin:
```nix
{
inputs.kopuz.url = "github:temidaradev/kopuz";
}
```
Ardından bunu sistem yapılandırmanıza aktarın ve derlemek yerine önceden
derlenmiş binary dosyasını indirmesi için Cachix substituter'ını ekleyin:
```nix
{
nix.settings = {
substituters = ["https://kopuz.cachix.org" ];
trusted-public-keys = ["kopuz.cachix.org-1:J2X3AnAYhKTJW5S3aCLoA1ckonQXVNZMQvhZA0YAufw="];
};
}
```
Ardından paketi kurun:
```nix
{pkgs, kopuz, ...}: let
kopuzPkg = kopuz.packages.${pkgs.stdenv.hostPlatform.system}.default
in {
environment.systemPackages = [kopuzPkg];
}
```
### AUR (Arch Linux)
Tercih ettiğiniz yardımcıyı kullanarak AUR'dan yükleyin:
```bash
yay -S kopuz-bin
# veya
paru -S kopuz-bin
```
### Flatpak (Recommended)
Kopuz yakında Flathub'da mevcut olacaktır. Kaynak manifest'inden (source
manifest) yüklemek için:
```bash
git clone https://github.com/temidaradev/kopuz
cd kopuz
flatpak-builder --user --install --force-clean build-dir packaging/flatpak/com.temidaradev.kopuz.json
flatpak run com.temidaradev.kopuz
```
Dosyaya tıklayıp bir uygulama sağlayıcı ile (örneğin KDE Discover) de
açabilirsiniz.
### AppImage
> [!IMPORTANT]
> AppImage, sisteminizde `webkit2gtk-4.1` ve `gtk3` kurulu olmasını gerektirir.
> Bu bağımlılıklar pakete dahil edilmemiştir.
>
> Modern bir masaüstü ortamına sahip çoğu dağıtımda bunlar zaten mevcuttur.
> Henüz kurulu değillerse bunları manuel olarak yüklemeniz gerekecektir.
Arch tabanlı dağıtımlarda, AppImage bir `WebKitNetworkProcess` hatasıyla
çökerse, uygulamayı şununla çalıştırın:
```bash
LD_LIBRARY_PATH=/usr/lib ./kopuz_*.AppImage
```
Veya bir kez sembolik bağlar (symlinks) oluşturun (sudo gerektirir):
```bash
sudo mkdir -p /usr/libexec/webkit2gtk-4.1
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitNetworkProcess /usr/libexec/webkit2gtk-4.1/
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitWebProcess /usr/libexec/webkit2gtk-4.1/
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitGPUProcess /usr/libexec/webkit2gtk-4.1/
```
### Build from Source
#### Dependencies
**Using Nix**
> [!TIP]
> Nix, Kopuz'un birincil geliştirme aracıdır ve sistemler arasında tutarlı, saf
> ve yeniden üretilebilir (reproducible) bir ortamda derleme bağımlılıklarını
> elde etmek için önerilen yöntemdir.
```bash
# Using Nix3 CLI
nix develop
```
Eğer bir Direnv kullanıcısıysanız, sağlanan `.envrc` dosyasını kullanın:
```bash
# Using Direnv
direnv allow
```
Geliştirme ortamı içinde kendi usershell'inizi kullanmaya devam etmek
istiyorsanız Direnv önerilir.
**Arch Linux Based Systems**
```bash
sudo pacman -S rust cargo dioxus-cli base-devel cmake pkgconf opus alsa-lib xdotool webkit2gtk-4.1 gtk3 libsoup3 openssl
```
**Debian Based Systems**
```bash
sudo apt install rustc cargo build-essential cmake pkg-config libopus-dev libasound2-dev libxdo-dev libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev libssl-dev
cargo install dioxus-cli
```
**Fedora Based Systems**
```bash
sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install rust cargo cmake pkgconf-pkg-config opus-devel alsa-lib-devel libxdo-devel webkit2gtk4.1-devel gtk3-devel libsoup3-devel openssl-devel
cargo install --locked dioxus-cli
```
**openSUSE Based Systems**
```bash
sudo zypper install rust cargo cmake pkg-config libopus-devel alsa-devel xdotool webkit2gtk3-soup2-devel gtk3-devel libsoup3-devel libopenssl-devel
cargo install --locked dioxus-cli
```
#### Developing Kopuz
```bash
# Clone the repository
$ git clone https://github.com/Kopuz-org/kopuz
# Move to the cloned directory
cd kopuz
# Install npm dependencies
npm install
# Serve project with Dioxus CLI
dx serve --package kopuz
```
### macOS
**Quarantine note:** Bunun yerine bir `.dmg` indirdiyseniz, macOS bunu
engelleyebilir. Karantina bayrağını temizlemek için bir kez çalıştırın:
```bash
xattr -d com.apple.quarantine /Applications/Kopuz.app
```
### Where does Kopuz keep its files?
Ayarlarınız, taranan kütüphane, playlist'ler ve favoriler tek bir **SQLite**
veritabanında, `kopuz.db`, config dizininde tutulur. Albüm kapakları ve
indirilen parçalar cache dizininde diskte kalır. (Debug build'leri ayrı bir
`kopuz-debug.db` kullanır, böylece `dx serve` gerçek verinize asla dokunmaz. DB
konumunu `KOPUZ_DB_PATH` env değişkeniyle değiştirebilirsiniz.)
**macOS** üzerinde:
- `~/Library/Application Support/com.temidaradev.kopuz/kopuz.db` - ayarlar,
kütüphane, playlist'ler, favoriler
- `~/Library/Caches/com.temidaradev.kopuz/covers/` - cached albüm kapakları
- `~/Library/Caches/com.temidaradev.kopuz/offline_tracks/` - indirilen parçalar
**Linux** üzerinde (XDG spec):
- `~/.config/kopuz/kopuz.db` - ayarlar, kütüphane, playlist'ler, favoriler
- `~/.cache/kopuz/covers/` - cached albüm kapakları
- `~/.cache/kopuz/offline_tracks/` - indirilen parçalar
**Windows** üzerinde (AppData):
- `%APPDATA%\temidaradev\kopuz\config\kopuz.db` - ayarlar, kütüphane,
playlist'ler, favoriler
- `%LOCALAPPDATA%\temidaradev\kopuz\cache\covers\` - cached albüm kapakları
- `%LOCALAPPDATA%\temidaradev\kopuz\cache\offline_tracks\` - indirilen parçalar
> [!NOTE]
> Eski bir sürümden mi yükseltiyorsunuz? İlk açılışta Kopuz mevcut
> `library.json` ve `playlists.json` dosyalarınızı `kopuz.db` içine aktarır ve
> geriye `*.json.bak` yedekleri bırakır. Eski JSON dosyaları bundan sonra
> okunmaz.
Kapaklar görünmüyorsa veya kütüphane hatalı görünüyorsa, cache klasörünü silip
rescan düğmesine basmanız yeterlidir.
## YouTube Music Setup
Kopuz, YouTube Music'i bir streaming backend'i olarak kullanabilir. Şuradan
ekleyin: **Settings → Media servers → Add → YouTube Music**.
### Choosing a mode
Kurulum iletişim kutusu iki yöntem sunar:
- **Sign in with a browser** - Kopuz, Google giriş sayfasını **isolated browser
profile** (a fresh, separate session; your normal browsing is never touched)
açar, giriş yapmanızı bekler ve oturum çerezlerini çıkarır. Hangi yüklü
Chromium ailesi tarayıcının (Chrome, Chromium, Brave, Edge veya Vivaldi)
kullanılacağını seçin. Bu, **library, Liked Music, playlists, and followed
artists** kilidini açar.
- **Continue without signing in (anonymous)** - giriş yok, çerez yok. **Göz
atabilir, arama yapabilir, sanatçı/albüm/playlist sayfalarını açabilir, mix
radyoyu başlatabilir ve herkese açık parçaları oynatabilirsiniz**. Liked
Music, library playlists, ve takip etme/beğenme devre dışı bırakılır (bu
görünümler bir "sign in to enable" uyarısı gösterir). Music Premium-only
parçalar anonim olarak oynatılamaz.
### Premium tracks
Music Premium kilitli parçalar, birincil yol `UNPLAYABLE` döndürdüğünde yerel
bir [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) resolve işlemine fallback
yapar, bu nedenle `yt-dlp`'nin kurulu olması bunlar için yardımcı olur. Anonim
mod, Premium-only içerikleri hiçbir şekilde oynatamaz.
## SoundCloud Setup
Kopuz, SoundCloud'u bir streaming backend'i olarak kullanabilir. Şuradan
ekleyin: **Settings → Media servers → Add → SoundCloud**.
Yazılacak bir URL veya parola yoktur. Kopuz, `soundcloud.com/signin` adresini
**izole bir tarayıcı profilinde** (taze, ayrı bir oturum; normal taramanıza asla
dokunulmaz) açar, giriş yapmanızı bekler ve oturumun `oauth_token` değerini
çıkarır. Hangi kurulu Chromium ailesi tarayıcının kullanılacağını seçin (Chrome,
Chromium, Brave, Edge veya Vivaldi).
Giriş yaptıktan sonra arama, parça oynatma (progressive MP3 artı Go+ AAC/HLS
stream'leri), **Beğenilen parçalarınız** favori olarak, playlist'lerinize salt
okunur erişim ve like/unlike elde edersiniz. Kaynağı kaldırmak izole profilini
temizler.
## Logs & Debugging
Kopuz, [`tracing`](https://docs.rs/tracing) aracılığıyla log tutar. Bunun büyük
bir kısmına uygulamanın kendisinden erişilebilir - **Settings → Logs** bölümünde
**Open logs folder**, **Export logs** ve **Enable Performance Tracing** geçişi
bulunur - böylece kullanıcıların yararlı bir rapor göndermek için asla bir
terminale ihtiyacı olmaz.
### Where the files live
Tüm dosyalar log dizininde yer alır (**Open logs folder** düğmesi doğrudan
buraya gider):
- Linux: `~/.cache/kopuz/logs/`
- macOS: `~/Library/Caches/com.temidaradev.kopuz/logs/`
- Windows: `%LOCALAPPDATA%\temidaradev\kopuz\cache\logs\`
| File | What it is |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `latest.log` | Mevcut oturum. Span zamanlaması + olaylar; canlı log. |
| `kopuz-
