<!--markdownlint-disable MD013 MD033 MD041 -->
<div align="center">
  <img src="../crates/kopuz/assets/banner.png" alt="Kopuz ലോഗോ" height="300"/>
  <h1>Kopuz</h1>
  <p>
    Rust ഉം Dioxus ഫ്രെയിംവർക്കും ഉപയോഗിച്ച് നിർമ്മിച്ച ആധുനികവും ഭാരം കുറഞ്ഞതുമായ
    ഒരു സംഗീത പ്ലെയർ ആപ്ലിക്കേഷനാണ് Kopuz. നിങ്ങളുടെ ലോക്കൽ സംഗീത ശേഖരം
    ക്രമീകരിക്കാനും ആസ്വദിക്കാനും സഹായിക്കുന്ന വൃത്തിയുള്ളതും വേഗത്തിൽ പ്രതികരിക്കുന്നതുമായ
    ഒരു ഇന്റർഫേസ് ഇത് നൽകുന്നു.
  </p>
  <a href="https://discord.gg/K6Bmzw2E4M">
    <img src="https://img.shields.io/badge/Discord-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord">
  </a>
  <img src="https://img.shields.io/badge/Rust-000000?style=flat&logo=rust&logoColor=white" alt="Rust">
  <img src="https://github.com/Kopuz-org/kopuz/actions/workflows/build.yml/badge.svg" alt="ബിൽഡ്">
  <img src="https://github.com/user-attachments/assets/3234bb1b-6702-4802-946a-32f46e63d225" alt="Kopuz">

<br/>
  <br/>
  <p>
    <a href="../README.md">English</a> | <a href="../README-TR.md">Türkçe</a> | <a href="../README-PT-PT.md">Português de Portugal</a> | <b> മലയാളം </b>
  </p>
</div>

## പേരിനെക്കുറിച്ച്

_കോപുസ്_ (kopuz) ഒരു പുരാതന തുർക്കിക് തന്തിവാദ്യമാണ്. മധ്യേഷ്യയിൽ ഉപയോഗിച്ചിരുന്ന
പല ല്യൂട്ട് (lute) വിഭാഗം വാദ്യങ്ങളുടെ പൂർവികനായി ഇത് സാധാരണയായി കണക്കാക്കപ്പെടുന്നു.
പരമ്പരാഗതമായി ഇത് കവികളും ശാമൻമാരും ഉപയോഗിച്ചിരുന്നു.

കിർഗിസ് _കൊമുസ്_ (komuz) അതേ വാദ്യമല്ലെങ്കിലും, _കോപുസ്_ന്റെ പിൻഗാമിയായിരിക്കാമെന്ന്
കരുതപ്പെടുന്നു. കസാഖ് _കോബിസ്_ (kobyz) ഇതുമായി ബന്ധപ്പെട്ട മറ്റൊരു വാദ്യമാണ്,
എന്നാൽ അത് വിരലുകൾ കൊണ്ട് മീട്ടുന്നതിന് പകരം വില്ല് ഉപയോഗിച്ച് വായിക്കുന്നതാണ്.
ഇതിന് വിപരീതമായി, തുവാൻ/യാക്കുത് _ഷോമുസ്_ (xomus) (ജോ ഹാർപ്പ്) പേരിലെ
സാമ്യം ഒഴികെ _കോപുസ്_യുമായി യാതൊരു ബന്ധവുമില്ല.

തുർക്കിക് ഇതിഹാസങ്ങളിൽ _കോപുസ്_ പ്രശസ്തനായ ഗായകനായ ഡെഡെ കോർക്കുട്ടുമായി
ബന്ധപ്പെട്ടതായി പറയപ്പെടുന്നു. എന്നാൽ ഇത് ചരിത്രപരമായ ഒരു വസ്തുതയല്ല,
മറിച്ച് പുരാണകഥകളുടെ ഭാഗമാണ്.

## അവലോകനം

നിങ്ങളുടെ ലോക്കൽ ഡയറക്ടറികളിലെ ഓഡിയോ ഫയലുകൾ സ്കാൻ ചെയ്യാനും,
Jellyfin അല്ലെങ്കിൽ Subsonic (Navidrome മുതലായവ) സെർവറുകളിൽ നിന്ന് സ്ട്രീം ചെയ്യാനും,
അല്ലെങ്കിൽ **YouTube Music** അല്ലെങ്കിൽ **SoundCloud** സ്ട്രീമിംഗ് ബാക്ക്‌എൻഡായി
കണക്റ്റ് ചെയ്യാനും Kopuz നിങ്ങളെ അനുവദിക്കുന്നു. ഇവയൊക്കെയും സ്വയം ക്രമീകരിച്ച്
എളുപ്പത്തിൽ ബ്രൗസ് ചെയ്യാവുന്ന ഒരു സംഗീത ലൈബ്രറിയായി അവതരിപ്പിക്കുന്നു.
കലാകാരൻമാർ, ആൽബങ്ങൾ, സംഗീതവിഭാഗങ്ങൾ (Genres) എന്നിവയുടെ അടിസ്ഥാനത്തിൽ
നാവിഗേറ്റ് ചെയ്യാനോ, നിങ്ങളുടെ സ്വന്തം പ്ലേലിസ്റ്റുകൾ പരിശോധിക്കാനോ കഴിയും.
Rust-ന്റെ പ്രകടനശേഷി പ്രയോജനപ്പെടുത്തി മികച്ച വേഗതയും ഡെസ്ക്ടോപ്പ് ഇന്റഗ്രേഷനും
ലക്ഷ്യമിട്ടാണ് ഈ ആപ്ലിക്കേഷൻ രൂപകൽപ്പന ചെയ്തിരിക്കുന്നത്.

ലൈബ്രറി, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ, ക്രമീകരണങ്ങൾ എന്നിവയെല്ലാം ലോക്കൽ
**SQLite** ഡാറ്റാബേസായ (`kopuz.db`) ൽ സൂക്ഷിക്കുന്നു. ഉപയോക്തൃ ഇന്റർഫേസ്
ഈ ഡാറ്റാബേസ് തത്സമയം വായിക്കുന്നതിനാൽ മാറ്റങ്ങൾ ഉടൻ തന്നെ പ്രതിഫലിക്കും.
ഓരോ മീഡിയ സോഴ്‌സിനും അതിന്റേതായ ലോഗിൻ വിവരങ്ങളും അതിന്റേതായ പ്രിയപ്പെട്ട
ഇനങ്ങളും പ്രത്യേകം സൂക്ഷിക്കപ്പെടുന്നു.


## സവിശേഷതകൾ

[jellyfin-plugin-listenbrainz]: https://github.com/lyarenei/jellyfin-plugin-listenbrainz

- **തീമുകൾ (Theming)**: ദൃശ്യരൂപം ഇഷ്ടാനുസരണം മാറ്റാൻ ഡൈനാമിക് തീമിംഗ് പിന്തുണ ഉൾപ്പെടുത്തിയിരിക്കുന്നു. എല്ലാ നിറ വേരിയബിളുകളിലും പൂർണ്ണ നിയന്ത്രണത്തോടെ നിങ്ങളുടെ സ്വന്തം കസ്റ്റം തീമും സൃഷ്ടിക്കാം.
- **നേറ്റീവ് ഇന്റഗ്രേഷൻ**: Linux (MPRIS), macOS (Now Playing / Remote Command Center), Windows (System Media Transport Controls) എന്നിവയിലെ സിസ്റ്റം മീഡിയ നിയന്ത്രണങ്ങളുമായി സംയോജിപ്പിക്കുന്നു.
- **മിനി പ്ലെയർ**: നിലവിൽ പ്ലേ ചെയ്യുന്ന ഗാനത്തിന്റെ ചെറിയ ദൃശ്യം കാണിക്കുന്ന കോംപാക്റ്റ് പ്ലെയർ ഓവർലേ. താഴെയുള്ള ബാറിൽ നിന്ന് ഇത് എപ്പോൾ വേണമെങ്കിലും തുറക്കുകയോ അടയ്ക്കുകയോ ചെയ്യാം.
- **ട്രേയിലേക്ക് ചുരുക്കുക (Minimize to Tray)**: ആപ്ലിക്കേഷൻ പൂർണ്ണമായി അടയ്ക്കുന്നതിന് പകരം സിസ്റ്റം ട്രേ ഐക്കണിലേക്ക് ചുരുക്കാനുള്ള സൗകര്യം. ഇതിലൂടെ പശ്ചാത്തലത്തിൽ സംഗീതം തുടർന്നും പ്ലേ ചെയ്യും. **Settings** ൽ നിന്ന് ഇത് പ്രവർത്തനക്ഷമമാക്കാം. Linux-ൽ ഇതിന് **appindicator** ലൈബ്രറി ആവശ്യമാണ് (Installation കുറിപ്പുകൾ കാണുക).
- **Discord RPC**: ഉൾനിർമ്മിത Discord RPC പിന്തുണ.
- **ഒന്നിലധികം ബാക്ക്‌എൻഡുകൾ**: Jellyfin അല്ലെങ്കിൽ Subsonic-അനുയോജ്യമായ സെർവറുകളിൽ നിന്ന് സംഗീതം സ്ട്രീം ചെയ്യുക (Navidrome മികച്ച രീതിയിൽ പ്രവർത്തിക്കുന്നു), YouTube Music അല്ലെങ്കിൽ SoundCloud കണക്റ്റ് ചെയ്യുക, അല്ലെങ്കിൽ ഒരു ലോക്കൽ ഫോൾഡർ മാത്രം ഉപയോഗിക്കുക. നിങ്ങൾക്ക് ഇഷ്ടമുള്ള രീതിയിൽ ഇവ സംയോജിപ്പിക്കാം. എല്ലാ മീഡിയ സോഴ്‌സുകളും ഒരൊറ്റ `MediaSource` ലെയറിലൂടെ ലഭ്യമാക്കപ്പെടുന്നു. ഓരോ സേവനത്തിനും പ്രത്യേകം കോഡ് എഴുതുന്നതിനുപകരം, അതിന്റെ കഴിവുകൾ (തിരയൽ, ഡൗൺലോഡുകൾ, റേഡിയോ, കണ്ടെത്തൽ, പ്രിയപ്പെട്ടവയുടെ സമന്വയം തുടങ്ങിയവ) അനുസരിച്ചാണ് ഉപയോക്തൃ ഇന്റർഫേസ് പ്രവർത്തിക്കുന്നത്.
- **YouTube Music**: Spotify-നെ ഓർമ്മിപ്പിക്കുന്ന **Discover** പേജ് (ശുപാർശ ചെയ്യുന്ന ഗാനങ്ങൾ, പ്ലേലിസ്റ്റുകൾ, ആൽബങ്ങൾ, കലാകാരന്മാർ, മൂഡുകൾ), സമ്പൂർണ്ണ **Artist Profiles** (ബാനർ, മികച്ച ഗാനങ്ങൾ, ആൽബങ്ങൾ, സിംഗിളുകൾ, ബന്ധപ്പെട്ട കലാകാരന്മാർ), ആൽബം/പ്ലേലിസ്റ്റ് ബ്രൗസിംഗ്, കൂടാതെ ഏത് ഗാനത്തിൽ നിന്നുമുള്ള **Mix Radio** ("Start Radio") എന്നിവ ഉൾപ്പെടുന്ന പൂർണ്ണ സ്ട്രീമിംഗ് ബാക്ക്‌എൻഡ്. നിങ്ങളുടെ ലൈബ്രറി, Liked Music, പ്ലേലിസ്റ്റുകൾ എന്നിവ ലഭിക്കാൻ അക്കൗണ്ടിൽ പ്രവേശിക്കാം. അല്ലെങ്കിൽ **അജ്ഞാത മോഡിൽ (Anonymous)** ലോഗിൻ ചെയ്യാതെ തന്നെ പൊതുവായ ഗാനങ്ങൾ ബ്രൗസ് ചെയ്യാനും തിരയാനും പ്ലേ ചെയ്യാനും കഴിയും. കൂടുതൽ വിവരങ്ങൾക്ക് [YouTube Music Setup](#youtube-music-setup) കാണുക.
- **SoundCloud**: തിരയൽ, ഗാന പ്ലേബാക്ക് (Progressive MP3, Go+ AAC/HLS), നിങ്ങളുടെ **Liked Tracks** പ്രിയപ്പെട്ടവയായി, വായനയ്ക്ക് മാത്രമുള്ള പ്ലേലിസ്റ്റുകൾ, Like/Unlike എന്നിവ ഉൾപ്പെടുന്ന സ്ട്രീമിംഗ് ബാക്ക്‌എൻഡ്. പ്രത്യേക ബ്രൗസർ പ്രൊഫൈൽ ഉപയോഗിച്ചുള്ള ഒരുതവണത്തെ സൈൻ-ഇൻ വഴി ഇത് ചേർക്കാം. കൂടുതൽ വിവരങ്ങൾക്ക് [SoundCloud Setup](#soundcloud-setup) കാണുക.
- **വരികളുടെ (Lyrics) പിന്തുണ**: തത്സമയം സമന്വയിപ്പിച്ച (Synced) വരികളും സാധാരണ വരികളും ലഭ്യമാണ്. സംഗീതത്തോടൊപ്പം സ്വയം സ്ക്രോൾ ചെയ്യുന്നതിനാൽ പിന്തുടരാൻ എളുപ്പമാണ്.
- **പ്രിയപ്പെട്ടവ (Favorites)**: ഗാനങ്ങളെ ലോക്കലായി പ്രിയപ്പെട്ടവയായി അടയാളപ്പെടുത്താം, അല്ലെങ്കിൽ Jellyfin/Subsonic സെർവറുമായി സമന്വയിപ്പിക്കാം.
- **പ്ലേലിസ്റ്റുകൾ**: സ്വന്തം പ്ലേലിസ്റ്റുകൾ സൃഷ്ടിക്കാനും നിയന്ത്രിക്കാനും, ഒറ്റ ഗാനങ്ങളോ മുഴുവൻ ആൽബങ്ങളോ ചേർക്കാനും, പ്ലേലിസ്റ്റുകൾ സെർവറുമായി സമന്വയിപ്പിക്കാനും കഴിയും.
- **സംഗീതവിഭാഗം (Genre) അനുസരിച്ചുള്ള ബ്രൗസിംഗ്**: ലോക്കലിലെയും സെർവറിലെയും സംഗീതം സംഗീതവിഭാഗങ്ങൾ (Genres) അനുസരിച്ച് പരിശോധിക്കാം.
- **ഫയൽ തരം ബാഡ്ജുകൾ**: ലോക്കൽ ഗാനങ്ങളുടെ പട്ടികയിൽ MP3, FLAC, WAV തുടങ്ങിയ ഫോർമാറ്റുകൾ ചെറിയ ബാഡ്ജുകളായി കാണിക്കും. ഇതിലൂടെ ഫയലിന്റെ ഫോർമാറ്റ് ഒറ്റനോട്ടത്തിൽ തിരിച്ചറിയാം.
- **തിരയൽ (Search)**: കലാകാരന്മാർ, ആൽബങ്ങൾ, ഗാനങ്ങൾ എന്നിവയിൽ തത്സമയ ഫലങ്ങളോടെ തിരയാം. കൂടാതെ എവിടെ നിന്നുമുള്ള **Quick Search** ഓവർലേ ഉപയോഗിച്ച് ആവശ്യമുള്ളതിലേക്ക് നേരിട്ട് പോകാനും കഴിയും.
- **ഇഷ്ടാനുസൃത UI ഫോണ്ടുകൾ**: ഉപയോക്തൃ ഇന്റർഫേസിനായി നിങ്ങളുടെ സ്വന്തം ഫോണ്ട് ഉപയോഗിച്ച് Kopuz-ന്റെ രൂപഭംഗി ഇഷ്ടാനുസരണം മാറ്റാം.
- **കേൾവി രേഖകൾ (Listening Logs)**: ഗാനങ്ങളുടെ പ്ലേ കൗണ്ട് ലോക്കലായി സൂക്ഷിക്കുന്നതിനാൽ നിങ്ങൾ ഏറ്റവും കൂടുതൽ കേൾക്കുന്ന ഗാനങ്ങൾ എളുപ്പത്തിൽ കണ്ടെത്താം.
- **Scrobbling**: ListenBrainz-ലേക്ക് Scrobble ചെയ്യാം. നിരവധി ക്ലയന്റുകൾ ഉപയോഗിക്കുന്ന Jellyfin ഉപയോക്താക്കൾക്ക് [jellyfin-plugin-listenbrainz] ഉപയോഗിക്കുന്നത് ശുപാർശ ചെയ്യുന്നു.


- **ഭാഷാ പിന്തുണ**: ഉപയോക്തൃ ഇന്റർഫേസ് അറബിക്, ബ്രസീലിയൻ പോർച്ചുഗീസ്, ഡച്ച്, ഇംഗ്ലീഷ്, യൂറോപ്യൻ പോർച്ചുഗീസ്, ഫിലിപ്പിനോ, ഫ്രഞ്ച്, ജർമ്മൻ, ഗ്രീക്ക്, ഹീബ്രു, ഹംഗേറിയൻ, ഇൻഡോനേഷ്യൻ, ഇറ്റാലിയൻ, ജാപ്പനീസ്, കൊറിയൻ, മലയാളം, പോളിഷ്, റൊമാനിയൻ, റഷ്യൻ, ലളിതവൽക്കരിച്ച ചൈനീസ്, സ്പാനിഷ്, സ്വീഡിഷ്, തമിഴ്, ടോക്കി പോന, തുർക്കിഷ്, യുക്രേനിയൻ, വിയറ്റ്നാമീസ്, കൂടാതെ സിറ്റെലൻ പോന (Sitelen Pona) എന്നിവയിൽ ലഭ്യമാണ്. പുതിയ ഭാഷകൾ ചേർക്കുന്നതിനും ലളിതമായ പ്രവൃത്തി പ്രവാഹം ലഭ്യമാണ്.
- **ഉയർന്ന പ്രകടനം (High Performance)**: പശ്ചാത്തലത്തിൽ നടക്കുന്ന കനത്ത പ്രോസസ്സിംഗും മികച്ച രീതിയിൽ ഒപ്റ്റിമൈസ് ചെയ്ത ലൈബ്രറി സ്കാനറും കാരണം ആപ്ലിക്കേഷൻ വളരെ വേഗത്തിൽ തുറക്കുകയും സുഗമമായി പ്രവർത്തിക്കുകയും, ഇതിനകം ഇൻഡക്സ് ചെയ്ത ഫയലുകൾ വീണ്ടും വേഗത്തിൽ ഒഴിവാക്കുകയും ചെയ്യുന്നു.
- **സ്വയമേവ വൃത്തിയാക്കൽ (Auto-Cleanup)**: ലൈബ്രറി വീണ്ടും സ്കാൻ ചെയ്യുമ്പോൾ ലഭ്യമല്ലാത്തതോ ഇല്ലാതാക്കിയതോ ആയ ഗാനങ്ങൾ സ്വയമേവ നീക്കം ചെയ്യപ്പെടും.
- **സുഗമമായ നാവിഗേഷൻ (Smooth Navigation)**: വ്യത്യസ്ത പേജുകളിലും കാഴ്ചകളിലും മാറുമ്പോൾ സ്ക്രോൾ സ്ഥാനം ശരിയായി പുനഃസജ്ജമാക്കുന്ന മിനുക്കിയ ഉപയോക്തൃ ഇന്റർഫേസ്.
- **ആനിമേഷനുകൾ കുറയ്ക്കുക (Reduce Animations)**: ശാന്തമായ ഉപയോക്തൃ അനുഭവം ആഗ്രഹിക്കുന്നവർക്ക് ചലന ഇഫക്റ്റുകൾ കുറയ്ക്കാനുള്ള ആക്സസിബിലിറ്റി ക്രമീകരണം.
- **ഇക്വലൈസർ (Equalizer)**: മുൻകൂട്ടി നൽകിയിരിക്കുന്ന പ്രീസെറ്റുകളും ഇഷ്ടാനുസൃത ക്രമീകരണങ്ങളും ഉൾക്കൊള്ളുന്ന ബിൽറ്റ്-ഇൻ 10-ബാൻഡ് ഇക്വലൈസർ ഉപയോഗിച്ച് ശബ്ദം സൂക്ഷ്മമായി ക്രമീകരിക്കാം.
- **ക്രോസ്‌ഫേഡ് (Crossfade)**: നേറ്റീവ് ഡെസ്ക്ടോപ്പ് പതിപ്പുകളിൽ ഗാനങ്ങൾക്കിടയിലെ മാറൽ കൂടുതൽ സുഗമമാക്കാൻ ട്രാക്കുകൾ തമ്മിൽ ലയിപ്പിക്കുന്നു. ബ്രൗസർ പതിപ്പിൽ നിലവിൽ സാധാരണ ട്രാക്ക് മാറൽ തന്നെയാണ് ഉപയോഗിക്കുന്നത്.
- **ചാനൽ മോഡ് (Channel Mode)**: `Stereo`, `Mono`, `Left only`, `Right only`, `Swap L/R` എന്നീ ഔട്ട്പുട്ട് മോഡുകൾക്കിടയിൽ മാറാം.
- **yt-dlp സംയോജനം**: `yt-dlp` ഉപയോഗിച്ച് YouTube-ലും മറ്റ് പിന്തുണയ്ക്കുന്ന സൈറ്റുകളിലും നിന്ന് നേരിട്ട് ഓഡിയോ ഡൗൺലോഡ് ചെയ്യാം. ഔട്ട്പുട്ട് ഫോർമാറ്റായി Best Audio, MP3, FLAC, WAV, അല്ലെങ്കിൽ MP4 വീഡിയോ തിരഞ്ഞെടുക്കാം. FLAC ശുപാർശ ചെയ്യുന്നില്ല, കാരണം `yt-dlp` നഷ്ടരഹിത (lossless) ഉറവിടത്തിൽ നിന്ന് ഡീകോഡ് ചെയ്യാതെ നിലവിലുള്ള നഷ്ടമുള്ള (lossy) ഓഡിയോ വീണ്ടും കണ്ടെയ്‌നറിലേക്ക് മാറ്റുകയാണ് (remux) ചെയ്യുന്നത്. SponsorBlock, ചാപ്റ്റർ വിഭജിക്കൽ, കുക്കികൾ, വേഗപരിധി (Rate Limiting) എന്നിവയും മറ്റ് നിരവധി സൗകര്യങ്ങളും പിന്തുണയ്ക്കുന്നു. ഇത് ഉപയോഗിക്കാൻ നിങ്ങളുടെ സിസ്റ്റത്തിൽ `yt-dlp` ഇൻസ്റ്റാൾ ചെയ്തിരിക്കണം.
- **മെറ്റാഡാറ്റ ക്രമീകരണങ്ങൾ (Metadata Settings)**: കലാകാരന്മാരുടെ ചിത്രങ്ങൾ എവിടെ നിന്ന് ലഭിക്കണമെന്ന് നിയന്ത്രിക്കാൻ Settings-ൽ പ്രത്യേക **Metadata** വിഭാഗം ലഭ്യമാണ്. **Album Cover** (ഡീഫോൾട്ട് — ആദ്യ ആൽബത്തിന്റെ കവർ ചിത്രം കലാകാരന്റെ ചിത്രമായി ഉപയോഗിക്കുന്നു) അല്ലെങ്കിൽ **Artist Photo** (Jellyfin അല്ലെങ്കിൽ Subsonic സെർവറിൽ നിന്ന് യഥാർത്ഥ കലാകാരന്റെ ചിത്രം ശേഖരിക്കുന്നു) എന്നിവയിൽ ഒന്നിനെ തിരഞ്ഞെടുക്കാം. **Artist Photo** മോഡിലേക്ക് മാറുമ്പോൾ Artists പേജ് തുറന്നയുടൻ ചിത്രങ്ങൾ പശ്ചാത്തലത്തിൽ സെർവറിൽ നിന്ന് ഡൗൺലോഡ് ചെയ്യും. ഒരു കലാകാരന് പ്രത്യേക ചിത്രം ലഭ്യമല്ലെങ്കിൽ, പകരം ആദ്യ ആൽബത്തിന്റെ കവർ ചിത്രം ഉപയോഗിക്കുന്നതിനാൽ ഒരിക്കലും ശൂന്യമായ ചിത്രം കാണിക്കില്ല.

## ഇൻസ്റ്റാളേഷൻ

### Cargo (crates.io)

Cargo ഉപയോഗിച്ച് നേരിട്ട് ഇൻസ്റ്റാൾ ചെയ്യുക:

```bash
cargo install --locked kopuz
```

### NixOS / Nix

**ഇൻസ്റ്റാൾ ചെയ്യാതെ നേരിട്ട് പ്രവർത്തിപ്പിക്കുക:**

```bash
nix run github:temidaradev/kopuz
```

**നിങ്ങളുടെ പ്രൊഫൈലിലേക്ക് ഇൻസ്റ്റാൾ ചെയ്യുക:**

```bash
nix profile add github:temidaradev/kopuz
```

**NixOS-ൽ flake ഉപയോഗിച്ച്:**

> [!TIP]
> `nix profile` ഉപയോഗിക്കുന്നതിനേക്കാൾ ഇത് ശുപാർശ ചെയ്യപ്പെടുന്നു, കാരണം ഇത് Kopuz-നെ ഐക്കണും `.desktop` എൻട്രിയും ഉൾപ്പെടുന്ന ഒരു യഥാർത്ഥ സിസ്റ്റം ആപ്ലിക്കേഷനായി ഇൻസ്റ്റാൾ ചെയ്യുന്നു.

നിങ്ങളുടെ `flake.nix`-ലെ `inputs`-ലേക്ക് Kopuz ചേർക്കുക:

```nix
{
  inputs.kopuz.url = "github:temidaradev/kopuz";
}
```

ശേഷം അത് നിങ്ങളുടെ സിസ്റ്റം കോൺഫിഗറേഷനിലേക്ക് കൈമാറുകയും Cachix substituter ചേർക്കുകയും ചെയ്യുക. ഇതിലൂടെ സോഴ്‌സിൽ നിന്ന് കമ്പൈൽ ചെയ്യാതെ തന്നെ മുൻകൂട്ടി നിർമ്മിച്ച ബൈനറി ഡൗൺലോഡ് ചെയ്യും:

```nix
{
  nix.settings = {
    substituters = ["https://kopuz.cachix.org"];
    trusted-public-keys = ["kopuz.cachix.org-1:J2X3AnAYhKTJW5S3aCLoA1ckonQXVNZMQvhZA0YAufw="];
  };
}
```

തുടർന്ന് പാക്കേജ് ഇൻസ്റ്റാൾ ചെയ്യുക:

```nix
{pkgs, kopuz, ...}: let
  kopuzPkg = kopuz.packages.${pkgs.stdenv.hostPlatform.system}.default;

in {
  environment.systemPackages = [kopuzPkg];
}
```

### AUR (Arch Linux)

നിങ്ങൾ ഇഷ്ടപ്പെടുന്ന AUR helper ഉപയോഗിച്ച് ഇൻസ്റ്റാൾ ചെയ്യുക:

```bash
yay -S kopuz-bin
# അല്ലെങ്കിൽ
paru -S kopuz-bin
```

### Flatpak (ശുപാർശ ചെയ്യുന്നത്)

Kopuz ഉടൻ തന്നെ Flathub-ൽ ലഭ്യമാകും. അതുവരെ source manifest ഉപയോഗിച്ച് ഇൻസ്റ്റാൾ ചെയ്യാം:

```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
```

ഫയലിൽ ക്ലിക്ക് ചെയ്ത് KDE Discover പോലുള്ള അനുയോജ്യമായ ഒരു ആപ്പ് സെന്റർ ഉപയോഗിച്ചും ഇത് തുറക്കാം.

### AppImage

> [!IMPORTANT]
> AppImage പ്രവർത്തിപ്പിക്കാൻ നിങ്ങളുടെ സിസ്റ്റത്തിൽ `webkit2gtk-4.1` ഉം `gtk3` ഉം ഇൻസ്റ്റാൾ ചെയ്തിരിക്കണം.
> ഈ ഡിപ്പൻഡൻസികൾ AppImage-യിൽ ഉൾപ്പെടുത്തിയിട്ടില്ല.
>
> കൂടാതെ സിസ്റ്റം ട്രേ ഐക്കൺ പ്രവർത്തിക്കാൻ **appindicator** ലൈബ്രറി (ഉദാ. `libayatana-appindicator`) ആവശ്യമാണ്. അത് ഇല്ലെങ്കിലും Kopuz സാധാരണ പോലെ പ്രവർത്തിക്കും, പക്ഷേ ട്രേ ഐക്കൺ കാണിക്കില്ല.
>
> ആധുനിക ഡെസ്ക്ടോപ്പ് എൻവയോൺമെന്റ് ഉപയോഗിക്കുന്ന മിക്ക Linux വിതരണങ്ങളിലും ഇവ ഇതിനകം ലഭ്യമായിരിക്കും. ലഭ്യമല്ലെങ്കിൽ നിങ്ങൾ സ്വയം ഇൻസ്റ്റാൾ ചെയ്യണം.

Arch അടിസ്ഥാനമാക്കിയുള്ള വിതരണങ്ങളിൽ AppImage `WebKitNetworkProcess` പിശകോടെ ക്രാഷ് ചെയ്യുകയാണെങ്കിൽ, ഇത് ഉപയോഗിച്ച് പ്രവർത്തിപ്പിക്കുക:

```bash
LD_LIBRARY_PATH=/usr/lib ./kopuz_*.AppImage
```

അല്ലെങ്കിൽ ഒരുതവണ symbolic links സൃഷ്ടിക്കാം (sudo ആവശ്യമാണ്):

```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)

#### ആവശ്യമായ ഡിപ്പൻഡൻസികൾ

**Nix ഉപയോഗിച്ച്**

> [!TIP]
> Kopuz വികസിപ്പിക്കുന്നതിനുള്ള പ്രധാന മാർഗമാണ് [Nix](https://nixos.org). ശുദ്ധവും (pure), പുനരാവർത്തിക്കാവുന്നതുമായ (reproducible), വിവിധ സിസ്റ്റങ്ങളിലുടനീളം ഒരേപോലെ പ്രവർത്തിക്കുന്ന വികസന പരിതസ്ഥിതിയിൽ ആവശ്യമായ എല്ലാ ബിൽഡ് ഡിപ്പൻഡൻസികളും ലഭ്യമാക്കുന്നതിനുള്ള ശുപാർശ ചെയ്യപ്പെടുന്ന രീതിയാണിത്.

```bash
# Nix3 CLI ഉപയോഗിച്ച്
nix develop
```

നിങ്ങൾ [Direnv](https://direnv.net) ഉപയോഗിക്കുന്ന ആളാണെങ്കിൽ, നൽകിയിരിക്കുന്ന `.envrc` ഫയൽ ഉപയോഗിക്കാം:

```bash
# Direnv ഉപയോഗിച്ച്
direnv allow
```

വികസന പരിതസ്ഥിതിക്കുള്ളിൽ തന്നെ നിങ്ങളുടെ സാധാരണ യൂസർ ഷെൽ ഉപയോഗിക്കുന്നത് തുടരാൻ ആഗ്രഹിക്കുന്നുവെങ്കിൽ Direnv ഉപയോഗിക്കുന്നത് ശുപാർശ ചെയ്യുന്നു.

> [!NOTE]
> **Minimize to Tray** സൗകര്യത്തിനായി ഉപയോഗിക്കുന്ന സിസ്റ്റം ട്രേ ഐക്കണിന് പ്രവർത്തനസമയത്ത് (runtime) **appindicator** ലൈബ്രറി ആവശ്യമാണ്. താഴെ നൽകിയിരിക്കുന്ന പാക്കേജ് ഡിപ്പൻഡൻസികളിൽ ഇത് ഉൾപ്പെടുത്തിയിട്ടുണ്ട്. ഇത് ഇല്ലെങ്കിൽ ട്രേ ഐക്കൺ മാത്രം കാണിക്കില്ല; വിൻഡോ അടയ്ക്കുമ്പോൾ അത് ട്രേയിലേക്ക് മറയുന്നതിനുപകരം ആപ്ലിക്കേഷൻ പൂർണ്ണമായും അടയ്ക്കും. എന്നിരുന്നാലും Kopuz സാധാരണ പോലെ പ്രവർത്തിക്കും. Nix development shell-ൽ ഈ ലൈബ്രറി ഇതിനകം ഉൾപ്പെടുത്തിയിട്ടുണ്ട്.

**Arch Linux അടിസ്ഥാനമാക്കിയുള്ള സിസ്റ്റങ്ങൾ**

```bash
sudo pacman -S rust cargo dioxus-cli base-devel cmake pkgconf opus alsa-lib xdotool webkit2gtk-4.1 gtk3 libsoup3 openssl libayatana-appindicator
```

**Debian അടിസ്ഥാനമാക്കിയുള്ള സിസ്റ്റങ്ങൾ**

```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 libayatana-appindicator3-1
cargo install dioxus-cli
```

**Fedora അടിസ്ഥാനമാക്കിയുള്ള സിസ്റ്റങ്ങൾ**

```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 libayatana-appindicator-gtk3
cargo install --locked dioxus-cli
```

**openSUSE അടിസ്ഥാനമാക്കിയുള്ള സിസ്റ്റങ്ങൾ**

```bash
sudo zypper install rust cargo cmake pkg-config libopus-devel alsa-devel xdotool webkit2gtk3-soup2-devel gtk3-devel libsoup3-devel libopenssl-devel libayatana-appindicator3-1
cargo install --locked dioxus-cli
```

#### Kopuz വികസിപ്പിക്കൽ

```bash
# റിപ്പോസിറ്ററി ക്ലോൺ ചെയ്യുക
git clone https://github.com/Kopuz-org/kopuz

# ക്ലോൺ ചെയ്ത ഡയറക്ടറിയിലേക്ക് പോകുക
cd kopuz

# npm ഡിപ്പൻഡൻസികൾ ഇൻസ്റ്റാൾ ചെയ്യുക
npm install

# Dioxus CLI ഉപയോഗിച്ച് പ്രോജക്റ്റ് പ്രവർത്തിപ്പിക്കുക
dx serve --package kopuz
```

### macOS

**Quarantine കുറിപ്പ്:** നിങ്ങൾ `.dmg` ഫയൽ ഡൗൺലോഡ് ചെയ്തിട്ടുണ്ടെങ്കിൽ macOS അത് പ്രവർത്തിക്കുന്നത് തടയാൻ സാധ്യതയുണ്ട്. Quarantine flag നീക്കം ചെയ്യാൻ താഴെ കാണുന്ന കമാൻഡ് ഒരുതവണ പ്രവർത്തിപ്പിക്കുക:

```bash
xattr -d com.apple.quarantine /Applications/Kopuz.app
```

### Kopuz അതിന്റെ ഫയലുകൾ എവിടെയാണ് സൂക്ഷിക്കുന്നത്?

നിങ്ങളുടെ ക്രമീകരണങ്ങൾ (Settings), സ്കാൻ ചെയ്ത ലൈബ്രറി, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ (Favorites) എന്നിവയെല്ലാം കോൺഫിഗറേഷൻ ഡയറക്ടറിയിലുള്ള ഒരൊറ്റ **SQLite** ഡാറ്റാബേസായ `kopuz.db`-ലാണ് സൂക്ഷിക്കുന്നത്. ആൽബം കവർ ചിത്രങ്ങളും ഡൗൺലോഡ് ചെയ്ത ട്രാക്കുകളും കാഷെ (cache) ഡയറക്ടറിയിൽ ഡിസ്കിൽ സൂക്ഷിക്കപ്പെടുന്നു. (Debug build-കൾ `kopuz-debug.db` എന്ന പ്രത്യേക ഡാറ്റാബേസ് ഉപയോഗിക്കുന്നതിനാൽ `dx serve` നിങ്ങളുടെ യഥാർത്ഥ ഡാറ്റയിൽ ഒരിക്കലും മാറ്റം വരുത്തില്ല. `KOPUZ_DB_PATH` എൻവയോൺമെന്റ് വേരിയബിൾ ഉപയോഗിച്ച് ഡാറ്റാബേസിന്റെ സ്ഥാനം നിങ്ങൾക്ക് മാറ്റാനുമാകും.)

**macOS-ൽ:**

- `~/Library/Application Support/com.temidaradev.kopuz/kopuz.db` — ക്രമീകരണങ്ങൾ, ലൈബ്രറി, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ
- `~/Library/Caches/com.temidaradev.kopuz/covers/` — കാഷെ ചെയ്ത ആൽബം കവർ ചിത്രങ്ങൾ
- `~/Library/Caches/com.temidaradev.kopuz/offline_tracks/` — ഡൗൺലോഡ് ചെയ്ത ട്രാക്കുകൾ

**Linux-ൽ** (XDG സ്പെസിഫിക്കേഷൻ):

- `~/.config/kopuz/kopuz.db` — ക്രമീകരണങ്ങൾ, ലൈബ്രറി, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ
- `~/.cache/kopuz/covers/` — കാഷെ ചെയ്ത ആൽബം കവർ ചിത്രങ്ങൾ
- `~/.cache/kopuz/offline_tracks/` — ഡൗൺലോഡ് ചെയ്ത ട്രാക്കുകൾ

**Windows-ൽ** (AppData):

- `%APPDATA%\temidaradev\kopuz\config\kopuz.db` — ക്രമീകരണങ്ങൾ, ലൈബ്രറി, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ
- `%LOCALAPPDATA%\temidaradev\kopuz\cache\covers\` — കാഷെ ചെയ്ത ആൽബം കവർ ചിത്രങ്ങൾ
- `%LOCALAPPDATA%\temidaradev\kopuz\cache\offline_tracks\` — ഡൗൺലോഡ് ചെയ്ത ട്രാക്കുകൾ

> [!NOTE]
> പഴയ പതിപ്പിൽ നിന്ന് അപ്‌ഗ്രേഡ് ചെയ്യുകയാണോ? ആദ്യമായി പ്രവർത്തിപ്പിക്കുമ്പോൾ Kopuz നിങ്ങളുടെ നിലവിലുള്ള `library.json` ഉം `playlists.json` ഉം `kopuz.db`-ലേക്ക് ഇമ്പോർട്ട് ചെയ്യും. അതേസമയം `*.json.bak` ബാക്കപ്പ് ഫയലുകളും സൃഷ്ടിക്കും. അതിനുശേഷം പഴയ JSON ഫയലുകൾ ഇനി ഉപയോഗിക്കുകയില്ല.

ആൽബം കവർ ചിത്രങ്ങൾ കാണുന്നില്ലെങ്കിൽ, അല്ലെങ്കിൽ ലൈബ്രറിയിൽ എന്തെങ്കിലും പ്രശ്നമുണ്ടെന്ന് തോന്നുകയാണെങ്കിൽ, കാഷെ ഫോൾഡർ ഇല്ലാതാക്കി വീണ്ടും **Rescan** ചെയ്താൽ മതിയാകും.

## YouTube Music Setup

Kopuz-നെ YouTube Music സ്ട്രീമിംഗ് ബാക്ക്‌എൻഡായി ഉപയോഗിക്കാം. ഇത് ചേർക്കാൻ **Settings → Media servers → Add → YouTube Music** എന്ന വഴി പിന്തുടരുക.

### ഒരു മോഡ് തിരഞ്ഞെടുക്കുക

സജ്ജീകരണ ഡയലോഗിൽ രണ്ട് രീതികൾ ലഭ്യമാണ്:

- **ബ്രൗസർ ഉപയോഗിച്ച് സൈൻ ഇൻ ചെയ്യുക** — Kopuz, Google-ന്റെ സൈൻ-ഇൻ പേജ് ഒരു **ഒറ്റപ്പെട്ട ബ്രൗസർ പ്രൊഫൈലിൽ (isolated browser profile)** തുറക്കും. ഇത് പുതിയതും നിങ്ങളുടെ സാധാരണ ബ്രൗസിംഗ് സെഷനിൽ നിന്ന് പൂർണ്ണമായും വേർതിരിച്ചിരിക്കുന്നതുമായ ഒരു പ്രൊഫൈലാണ്. നിങ്ങളുടെ പതിവ് ബ്രൗസിംഗ് ഡാറ്റയിലോ സെഷനിലോ യാതൊരു മാറ്റവും ഉണ്ടാകില്ല. നിങ്ങൾ ലോഗിൻ ചെയ്ത ശേഷം Kopuz ആവശ്യമായ സെഷൻ കുക്കികൾ ശേഖരിക്കും. Chrome, Chromium, Brave, Edge, Vivaldi, Helium എന്നിവയിൽ ഇൻസ്റ്റാൾ ചെയ്തിരിക്കുന്ന ബ്രൗസറുകളിൽ ഏതെങ്കിലും തിരഞ്ഞെടുക്കാം. ഇതിലൂടെ നിങ്ങളുടെ **ലൈബ്രറി, Liked Music, പ്ലേലിസ്റ്റുകൾ, പിന്തുടരുന്ന (Followed) കലാകാരന്മാർ** എന്നിവ ലഭ്യമാകും.

- **സൈൻ ഇൻ ചെയ്യാതെ തുടരുക (Anonymous)** — ലോഗിൻ ചെയ്യുകയോ കുക്കികൾ ഉപയോഗിക്കുകയോ വേണ്ടതില്ല. നിങ്ങൾക്ക് **ബ്രൗസ് ചെയ്യാനും, തിരയാനും, കലാകാരൻ/ആൽബം/പ്ലേലിസ്റ്റ് പേജുകൾ തുറക്കാനും, Mix Radio ആരംഭിക്കാനും, പൊതുവായി ലഭ്യമായ ഗാനങ്ങൾ പ്ലേ ചെയ്യാനും** കഴിയും. എന്നാൽ Liked Music, ലൈബ്രറി പ്ലേലിസ്റ്റുകൾ, Follow/Like പോലുള്ള സവിശേഷതകൾ പ്രവർത്തനരഹിതമായിരിക്കും. അവിടങ്ങളിൽ "സജീവമാക്കാൻ സൈൻ ഇൻ ചെയ്യുക" എന്ന സന്ദേശം കാണിക്കും. Music Premium-ന് മാത്രം ലഭ്യമായ ഗാനങ്ങൾ Anonymous മോഡിൽ പ്ലേ ചെയ്യാൻ കഴിയില്ല.

### Premium ഗാനങ്ങൾ

Music Premium-ന് മാത്രമായി ലഭ്യമായ ഗാനങ്ങൾ പ്ലേ ചെയ്യാൻ ശ്രമിക്കുമ്പോൾ പ്രധാന സ്ട്രീമിംഗ് മാർഗം `UNPLAYABLE` തിരികെ നൽകുന്നുവെങ്കിൽ, Kopuz ലോക്കലായി ഇൻസ്റ്റാൾ ചെയ്തിരിക്കുന്ന [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) ഉപയോഗിച്ച് പകരം പരിഹരിക്കാൻ (resolve) ശ്രമിക്കും. അതിനാൽ `yt-dlp` ഇൻസ്റ്റാൾ ചെയ്തിരിക്കുന്നത് ഉപകാരപ്രദമാണ്. എന്നിരുന്നാലും Anonymous മോഡിൽ Premium-ന് മാത്രമായുള്ള ഉള്ളടക്കം പ്ലേ ചെയ്യാൻ സാധിക്കില്ല.


## SoundCloud Setup

Kopuz-നെ SoundCloud സ്ട്രീമിംഗ് ബാക്ക്‌എൻഡായി ഉപയോഗിക്കാം. ഇത് ചേർക്കാൻ **Settings → Media servers → Add → SoundCloud** എന്ന വഴി പിന്തുടരുക.

നൽകേണ്ട URL-യോ പാസ്‌വേഡോ ഒന്നുമില്ല. Kopuz `soundcloud.com/signin` ഒരു **ഒറ്റപ്പെട്ട ബ്രൗസർ പ്രൊഫൈലിൽ (isolated browser profile)** തുറക്കും. ഇത് പുതിയതും നിങ്ങളുടെ സാധാരണ ബ്രൗസിംഗ് സെഷനിൽ നിന്ന് പൂർണ്ണമായും വേർതിരിച്ചിരിക്കുന്നതുമായ ഒരു പ്രൊഫൈലാണ്. നിങ്ങളുടെ പതിവ് ബ്രൗസിംഗ് ഡാറ്റയെ ഇത് ഒരിക്കലും സ്പർശിക്കില്ല. നിങ്ങൾ ലോഗിൻ ചെയ്ത ശേഷം സെഷനിലെ `oauth_token` Kopuz ശേഖരിക്കും. Chrome, Chromium, Brave, Edge, Vivaldi, അല്ലെങ്കിൽ Helium എന്നിവയിൽ ഇൻസ്റ്റാൾ ചെയ്തിരിക്കുന്ന ഏതെങ്കിലും Chromium-അധിഷ്ഠിത ബ്രൗസർ തിരഞ്ഞെടുക്കാം.

സൈൻ ഇൻ ചെയ്ത ശേഷം നിങ്ങൾക്ക് തിരയൽ, ഗാന പ്ലേബാക്ക് (Progressive MP3, Go+ AAC/HLS സ്ട്രീമുകൾ), നിങ്ങളുടെ **Liked Tracks** പ്രിയപ്പെട്ടവയായി കാണൽ, പ്ലേലിസ്റ്റുകൾക്ക് വായിക്കാൻ മാത്രമുള്ള (read-only) ആക്‌സസ്, കൂടാതെ Like/Unlike ചെയ്യാനുള്ള സൗകര്യങ്ങൾ ലഭിക്കും. ഈ മീഡിയ സോഴ്‌സ് നീക്കം ചെയ്താൽ അതുമായി ബന്ധപ്പെട്ട ഒറ്റപ്പെട്ട ബ്രൗസർ പ്രൊഫൈലും സ്വയമേവ നീക്കം ചെയ്യപ്പെടും.


## ലോഗുകളും ഡീബഗിംഗും

Kopuz [`tracing`](https://docs.rs/tracing) ഉപയോഗിച്ചാണ് ലോഗുകൾ രേഖപ്പെടുത്തുന്നത്. ഇതിലെ ഭൂരിഭാഗം സൗകര്യങ്ങളും ആപ്ലിക്കേഷനിൽ തന്നെയുണ്ട് — **Settings → Logs** എന്ന ഭാഗത്ത് **Open logs folder**, **Export logs**, കൂടാതെ **Enable Performance Tracing** എന്ന ഓപ്ഷനും ലഭ്യമാണ്. അതിനാൽ ഉപകാരപ്രദമായ ഒരു ബഗ് റിപ്പോർട്ട് അയയ്ക്കാൻ ഉപയോക്താക്കൾക്ക് ടെർമിനൽ ഉപയോഗിക്കേണ്ടതില്ല.

### ലോഗ് ഫയലുകൾ എവിടെയാണ് സൂക്ഷിക്കുന്നത്?

എല്ലാ ലോഗ് ഫയലുകളും ലോഗ് ഡയറക്ടറിയിലാണ് സൂക്ഷിക്കുന്നത് (**Open logs folder** ബട്ടൺ നിങ്ങളെ നേരിട്ട് അവിടേക്ക് കൊണ്ടുപോകും):

- Linux: `~/.cache/kopuz/logs/`
- macOS: `~/Library/Caches/com.temidaradev.kopuz/logs/`
- Windows: `%LOCALAPPDATA%\temidaradev\kopuz\cache\logs\`

| ഫയൽ | വിവരണം |
| ---- | -------- |
| `latest.log` | നിലവിലെ സെഷന്റെ ലോഗ്. Span timing-ഉം ഇവന്റുകളും ഉൾപ്പെടുന്ന തത്സമയ ലോഗ്. |
| `kopuz-<timestamp>.log` | മുമ്പത്തെ സെഷനുകളുടെ ലോഗുകൾ. ആപ്ലിക്കേഷൻ ആരംഭിക്കുമ്പോൾ സ്വയമേവ ആർക്കൈവ് ചെയ്യപ്പെടുന്നു (അവസാന 10 എണ്ണം മാത്രം സൂക്ഷിക്കും). ആപ്ലിക്കേഷൻ വീണ്ടും ആരംഭിച്ചാലും അതിന് മുമ്പത്തെ സെഷന്റെ ലോഗ് ഇല്ലാതാകില്ല. |
| `crash-<timestamp>.txt` | **ആപ്ലിക്കേഷൻ ക്രാഷ് ചെയ്താൽ മാത്രം** (Rust panic) സൃഷ്ടിക്കുന്ന റിപ്പോർട്ട്. പിശക് സന്ദേശം, backtrace, സമീപകാല ലോഗുകളുടെ അവസാന ഭാഗം, ആപ്ലിക്കേഷൻ പതിപ്പ്, ഓപ്പറേറ്റിംഗ് സിസ്റ്റം പതിപ്പ് എന്നിവ ഉൾക്കൊള്ളുന്നു. |
| `kopuz-trace.json` | Performance Trace ഫയൽ. Performance Tracing പ്രവർത്തനക്ഷമമാക്കിയാൽ മാത്രം സൃഷ്ടിക്കപ്പെടും (താഴെ കാണുക). ഓരോ പ്രവർത്തനത്തിലും ഇത് പുതുക്കി എഴുതപ്പെടും. |

Timestamp-കൾ UTC സമയമേഖലയിലെ `YYYY-MM-DD_HH-MM-SS` ഫോർമാറ്റിലാണ് ഉപയോഗിക്കുന്നത്. അതിനാൽ ഫയലുകൾ സമയക്രമത്തിൽ സ്വയമേവ ക്രമീകരിക്കപ്പെടും.


### പ്രശ്നപരിഹാരത്തിനുള്ള ചുരുക്ക മാർഗ്ഗരേഖ (Triage cheat-sheet)

**ആപ്ലിക്കേഷൻ ക്രാഷ് ആയി →** സ്വയമേവ ഒരു `crash-<timestamp>.txt` ഫയൽ സൃഷ്ടിക്കപ്പെടും. ഉപയോക്താവിനോട് **Settings → Logs → Export logs** ഉപയോഗിക്കാൻ ആവശ്യപ്പെടുക (ഇത് `latest.log` ഉം ഏറ്റവും പുതിയ crash report ഉം ഒരൊറ്റ ഫയലായി ചേർക്കും), അല്ലെങ്കിൽ **Open logs folder** തുറന്ന് ഏറ്റവും പുതിയ `crash-*.txt` ഫയൽ എടുക്കുക.

**പ്രകടന പ്രശ്നം (freeze / വേഗക്കുറവ് / തടസ്സപ്പെടൽ) →** ഉപയോക്താവിനോട് താഴെ പറയുന്ന കാര്യങ്ങൾ ചെയ്യാൻ ആവശ്യപ്പെടുക:

1. **Settings → Logs → "Performance Tracing" പ്രവർത്തനക്ഷമമാക്കുക**, തുടർന്ന് ആപ്ലിക്കേഷൻ **restart** ചെയ്യുക (ഈ ഓപ്ഷൻ ഇതിനായി മുന്നറിയിപ്പ് നൽകും — trace recorder ആപ്ലിക്കേഷൻ ആരംഭിക്കുമ്പോൾ ഒരിക്കൽ മാത്രം സജ്ജീകരിക്കപ്പെടുന്നു).
2. വേഗക്കുറവ് അനുഭവപ്പെടുന്ന പ്രവർത്തനം വീണ്ടും ചെയ്യുക.
3. **ആപ്ലിക്കേഷൻ പൂർണ്ണമായി അടയ്ക്കുക** (ഇത് trace ഫയൽ ശരിയായി save ചെയ്യാൻ സഹായിക്കും).
4. **Settings → Logs → Open logs folder** തുറന്ന് `kopuz-trace.json` അയയ്ക്കുക (അല്ലെങ്കിൽ **Export logs** ഉപയോഗിക്കുക).

Trace ഫയൽ [speedscope.app](https://speedscope.app) അല്ലെങ്കിൽ [ui.perfetto.dev](https://ui.perfetto.dev) ഉപയോഗിച്ച് തുറക്കാം. പ്രധാനപ്പെട്ട പ്രവർത്തനപാതകൾ (YouTube stream resolve, browse/search/pagination, Mix Radio, library scan, downloads, playback transitions, ഓരോ component-ന്റെയും renders എന്നിവ) പേരുള്ള spans ആയി രേഖപ്പെടുത്തുന്നു. ഒരു പ്രവർത്തനം ആരംഭിച്ച worker thread-ലെ പ്രവർത്തനങ്ങൾ അതിന്റെ കീഴിൽ ക്രമീകരിക്കപ്പെടുന്നതിനാൽ, സമയത്തിന്റെ ഭൂരിഭാഗവും എവിടെയാണ് ചെലവാകുന്നതെന്ന് trace വ്യക്തമായി കാണിക്കും.

നീണ്ട സെഷനുകളിൽ trace ഫയലിന്റെ വലുപ്പം വർധിക്കുകയും ചെറിയ performance overhead ഉണ്ടാകുകയും ചെയ്യുന്നതിനാൽ, പരിശോധന പൂർത്തിയായ ശേഷം ഇത് വീണ്ടും ഓഫ് ചെയ്യുക.

### Power-user എൻവയോൺമെന്റ് വേരിയബിളുകൾ

ടെർമിനലിൽ പ്രവർത്തിപ്പിക്കുമ്പോൾ ലോഗുകളുടെ **verbosity** എൻവയോൺമെന്റ് വേരിയബിളുകൾ ഉപയോഗിച്ച് നിയന്ത്രിക്കാം:

```bash
# ഒരു സെഷനിലേക്കുള്ള വിശദമായ (debug-level) ലോഗുകൾ
KOPUZ_DEBUG=1 kopuz

# ഓരോ മോഡ്യൂളിനും കൂടുതൽ കൃത്യമായ നിയന്ത്രണം (KOPUZ_DEBUG-നെ മറികടക്കും);
# സാധാരണ tracing directive syntax ഉപയോഗിക്കുന്നു
KOPUZ_LOG="server::ytmusic=trace,kopuz=debug" kopuz

# ആഴത്തിലുള്ള render-tree profiling:
# Dioxus-ന്റെ സ്വന്തം per-component render/diff spans
# (ആദ്യം Settings-ൽ trace toggle പ്രവർത്തനക്ഷമമാക്കുക;
# ഇവിടെ രേഖപ്പെടുത്തേണ്ട വിവരങ്ങൾ മാത്രമാണ് നിയന്ത്രിക്കുന്നത്)
KOPUZ_LOG="info,dioxus_core=trace" kopuz
```

`RUST_LOG` ഉം പ്രവർത്തിക്കും; എന്നാൽ `KOPUZ_LOG`-ന് മുൻഗണന ലഭിക്കും.

**Performance Trace** പ്രവർത്തനക്ഷമമാക്കുന്നത് **Settings → Logs → Enable Performance Tracing** വഴിയാണ് മാത്രം (ശേഷം restart ചെയ്യണം). ഇതിനായി യാതൊരു environment variable-വും ഇല്ല; UI തന്നെയാണ് പ്രധാന നിയന്ത്രണ കേന്ദ്രം. ഡീഫോൾട്ടായി ഇത് ഓഫ് ആയിരിക്കും → അതിനാൽ അധിക performance overhead ഒന്നുമില്ല.

> Debug builds-ൽ Settings → Logs വിഭാഗത്തിൽ **Trigger crash** എന്ന ബട്ടൺ ഉണ്ടായിരിക്കും. ഇത് crash-report സംവിധാനം പരിശോധിക്കാൻ ഉപയോഗിക്കാം. Release builds-ൽ ഇത് ഉൾപ്പെടുത്തിയിട്ടില്ല.


## ഒപ്റ്റിമൈസേഷൻ (Optimization)

വലിയ ലൈബ്രറികളോടുകൂടിയും വേഗതയേറിയ അനുഭവം നൽകുന്നതിനാണ് Kopuz നിർമ്മിച്ചിരിക്കുന്നത്. ഇതിന് പിന്നിൽ ഞങ്ങൾ ചെയ്യുന്ന പ്രധാന കാര്യങ്ങൾ:

- **ഇതിനകം ഇൻഡക്സ് ചെയ്തവ ഒഴിവാക്കുന്നു** — സ്കാനർ ഇതിനകം കണ്ടിട്ടുള്ള എല്ലാ പാതകളുടെയും (`path`) ഒരു `HashSet` സൂക്ഷിക്കുന്നു. അതിനാൽ വീണ്ടും സ്കാൻ ചെയ്യുമ്പോൾ പുതിയ ഫയലുകൾ മാത്രം പരിശോധിക്കും. ഉദാഹരണത്തിന്, നിങ്ങളുടെ കൈവശം 10,000 ട്രാക്കുകൾ ഉണ്ടെന്നും പിന്നീട് 5 പുതിയ ട്രാക്കുകൾ ചേർത്തുവെന്നും കരുതുക. Kopuz ബാക്കിയുള്ള 9,995 ഫയലുകളും വീണ്ടും വായിക്കില്ല. പ്രത്യേകിച്ച് HDD-കളിൽ ഇത് വലിയ വ്യത്യാസം ഉണ്ടാക്കുന്നു.

- **സമാന്തര സ്റ്റാർട്ടപ്പ് ലോഡിംഗ് (Parallel startup loading)** — ആപ്ലിക്കേഷൻ ആരംഭിക്കുമ്പോൾ ലൈബ്രറി, കോൺഫിഗറേഷൻ, പ്ലേലിസ്റ്റുകൾ, പ്രിയപ്പെട്ടവ എന്നിവയെല്ലാം `tokio::join!` ഉപയോഗിച്ച് ഒരേസമയം ലോഡ് ചെയ്യുന്നു. ഈ മാറ്റത്തിന് മുമ്പ് ഓരോന്നും ക്രമത്തിൽ ലോഡ് ചെയ്യേണ്ടി വന്നതിനാൽ കുറച്ച് സമയം ശൂന്യമായ വിൻഡോ കാണേണ്ടി വരുമായിരുന്നു. ഇപ്പോൾ ഇത് ഏകദേശം തൽക്ഷണം നടക്കുന്നു.

- **ആൽബം ആർട്ട് കാഷിംഗ്** — കവർ ചിത്രങ്ങൾ ഒരിക്കൽ മാത്രം എക്സ്ട്രാക്റ്റ് ചെയ്ത് ഡിസ്കിൽ സൂക്ഷിക്കുന്നു (`~/.cache/kopuz/covers/` Linux-ൽ, `~/Library/Caches/` macOS-ൽ). കൂടാതെ macOS-ന്റെ now-playing artwork object മെമ്മറിയിൽ കാഷ് ചെയ്യുന്നതിനാൽ progress bar പുതുക്കുമ്പോഴെല്ലാം ചിത്രം വീണ്ടും decode ചെയ്യേണ്ടതില്ല.

- **Lazy loading ചിത്രങ്ങൾ** — തിരയൽ ഫലങ്ങൾ, ട്രാക്ക് നിരകൾ, genre views എന്നിവയിലെ ആൽബം കവർ ചിത്രങ്ങൾ എല്ലാം `loading="lazy"` ഉപയോഗിക്കുന്നു. അതിനാൽ വലിയ ലൈബ്രറിയിലൂടെ സ്ക്രോൾ ചെയ്യുമ്പോൾ നൂറുകണക്കിന് ചിത്രങ്ങൾ ഒരേസമയം ലോഡ് ചെയ്യേണ്ടതില്ല.

- **ബ്ലോക്ക് ചെയ്യാത്ത I/O (Non-blocking I/O)** — മെറ്റാഡാറ്റ parsing, ഫയൽ സ്കാനിംഗ്, ലൈബ്രറി സംരക്ഷിക്കൽ തുടങ്ങിയ ഭാരമേറിയ പ്രവർത്തനങ്ങൾ `spawn_blocking` threads-ൽ പ്രവർത്തിക്കുന്നു. അതിനാൽ ഉപയോക്തൃ ഇന്റർഫേസ് ഒരിക്കലും freeze ആകില്ല. പൂർണ്ണ ലൈബ്രറി സ്കാൻ നടക്കുമ്പോഴും പ്രധാന thread പ്രതികരണക്ഷമമായി തുടരും.

- **മികച്ച sorting സംവിധാനം (Smarter sorting)** — ലൈബ്രറി views-ൽ സാധാരണ `sort_by_key`-ന് പകരം `sort_by_cached_key` ഉപയോഗിക്കുന്നു. ഇതിലൂടെ ഓരോ comparison സമയത്തും sort key (ഉദാ. `.to_lowercase()`) വീണ്ടും കണക്കാക്കേണ്ടതില്ല. ചെറിയൊരു മാറ്റം പോലെ തോന്നാമെങ്കിലും ആയിരക്കണക്കിന് ട്രാക്കുകളുള്ളപ്പോൾ ഇതിന്റെ പ്രയോജനം വലുതാണ്.

- **Artwork-നുള്ള HTTP caching** — കസ്റ്റം `artwork://` പ്രോട്ടോക്കോൾ ചിത്രങ്ങൾ `Cache-Control: public, max-age=31536000` ഉപയോഗിച്ച് നൽകുന്നു. അതിനാൽ Webview-ന് ഇതിനകം ലഭിച്ച കവർ ചിത്രങ്ങൾ വീണ്ടും ആവശ്യപ്പെടേണ്ടതില്ല.

മൊത്തത്തിൽ, ഈ മാറ്റങ്ങൾ rescanning സമയം **വളരെ കുറയ്ക്കുകയും**, പ്രത്യേകിച്ച് 5000-ലധികം ട്രാക്കുകളുള്ള ലൈബ്രറികളിൽ ആപ്ലിക്കേഷൻ കൂടുതൽ പ്രതികരണക്ഷമമാക്കുകയും ചെയ്തു. മെമ്മറി ഉപയോഗവും നിയന്ത്രിതമായി തുടരുന്നു, കാരണം decode ചെയ്ത ചിത്രങ്ങൾ ആവശ്യത്തിനേക്കാൾ കൂടുതൽ സമയം മെമ്മറിയിൽ സൂക്ഷിക്കുന്നില്ല.


## ടെക് സ്റ്റാക്ക് (Tech Stack)

- **Dioxus**: ഉപയോക്തൃ ഇന്റർഫേസ് ഫ്രെയിംവർക്ക്
- **Symphonia**: ഓഡിയോ ഡീകോഡിംഗ് ലൈബ്രറി
- **Cpal**: ഓഡിയോ I/O ലൈബ്രറി
- **Lofty**: മെറ്റാഡാറ്റ parsing ലൈബ്രറി
- **SQLite / sqlx**: compile-time പരിശോധിക്കപ്പെടുന്ന queries ഉപയോഗിച്ചുള്ള ലോക്കൽ സ്റ്റോറേജ്
- **TailwindCSS**: CSS അടിസ്ഥാനമാക്കിയുള്ള സ്റ്റൈലിംഗ് ഫ്രെയിംവർക്ക്

## ക്രിപ്റ്റോ സംഭാവന (Crypto Donation)

- **Solana**: "2fapJYRztnTRLpJbmyEUnsuZ36AzLK2JrMmmLEfDqKpN"
- **Bitcoin**: "bc1qz94yz9xvufa6hxlvjzaajgd2zyfu86arn68hu4"
- **Monero**:
  "86mz3HxTrKyYpuvx78m6pufbXdwAnoyoZBztz6HyYrnM1XP5YVrMy9jTVRY5vzgGtkizACLpFwHEdafKTMoj6y8mAVgvWMz"
- **Ethereum**: "0xa490D50470cdFf837B6663F7f6cBe50B157224e5"
- **USDT on Solana Chain**: "GYmnAcrA5MbF6cUxT2m5d5cwdfr14qSY9WFYRwXxaibW"

## ക്രെഡിറ്റുകൾ (Credits)

- ലോഗോ ഡിസൈൻ ചെയ്തത്: Lucas Amorim -
  [അദ്ദേഹത്തിന്റെ Instagram അക്കൗണ്ട്](https://www.instagram.com/yattets/)

## സ്റ്റാർ ചരിത്രം (Star History)

[![Star History Chart](https://api.star-history.com/chart?repos=Kopuz-org/kopuz&type=date&legend=top-left)](https://www.star-history.com/?repos=Kopuz-org%2Fkopuz&type=date&legend=top-left)

