@ -1458,7 +1458,7 @@ const DOCS_SECTIONS = [
< li > < strong > UI Appearance < / s t r o n g > & m d a s h ; C u s t o m a c c e n t c o l o r s w i t h p e r s i s t e n t p r e f e r e n c e . C h a n g e s a p p l y i m m e d i a t e l y a c r o s s t h e e n t i r e i n t e r f a c e . C h o o s e f r o m d i f f e r e n t < s t r o n g > s i d e b a r v i s u a l i z e r t y p e s < / s t r o n g > f o r t h e m e d i a p l a y e r a u d i o v i s u a l i z a t i o n . < / l i >
< li > < strong > API Keys < / s t r o n g > & m d a s h ; G e n e r a t e a n d m a n a g e A P I k e y s f o r t h e R E S T A P I . K e y s u s e a < c o d e > s k _ < / c o d e > p r e f i x a n d a r e s h o w n o n c e a t c r e a t i o n & m d a s h ; o n l y a S H A - 2 5 6 h a s h i s s t o r e d f o r s e c u r i t y . < / l i >
< li > < strong > Path Templates < / s t r o n g > & m d a s h ; C o n f i g u r e h o w f i l e s a r e o r g a n i z e d i n y o u r l i b r a r y . T h e d e f a u l t t e m p l a t e i s < c o d e > A r t i s t / A l b u m / T r a c k N u m - T i t l e . e x t < / c o d e > < / l i >
< li > < strong > Log Level < / s t r o n g > & m d a s h ; S e t th e a p p l i c a t i o n lo g v e r b o s i t y ( D E B U G , I N F O , W A R N I N G , E R R O R ) fr o m t h e S e t t i n g s p a g e . C h a n g e s t a k e e f f e c t i m m e d i a t e l y w i t h o u t r e s t a r t . U s e f u l f o r t r o u b l e s h o o t i n g i s s u e s . < / l i >
< li > < strong > Log Level < / s t r o n g > & m d a s h ; S e t o g v e r b o s i t y ( D E B U G , I N F O , W A R N I N G , E R R O R ) in < s t r o n g > S e t t i n g s & r a r r ; A d v a n c e d & r a r r ; L o g g i n g < / s t r o n g > . C h a n g e s t a k e e f f e c t i m m e d i a t e l y . S e e < e m > T r o u b l e s h o o t i n g & r a r r ; U n d e r s t a n d i n g L o g s < / e m > f o r d e t a i l s . < / l i >
< li > < strong > WebSocket < / s t r o n g > & m d a s h ; R e a l - t i m e s t a t u s u p d a t e s a r e d e l i v e r e d v i a W e b S o c k e t . A l l d o w n l o a d s , e n r i c h m e n t p r o g r e s s , s c a n s t a t u s , a n d s y s t e m e v e n t s p u s h t o t h e U I w i t h o u t p o l l i n g . < / l i >
< li > < strong > Music Library Paths < / s t r o n g > & m d a s h ; I n S e t t i n g s & g t ; L i b r a r y , a d d f o l d e r p a t h s w h e r e y o u r m u s i c f i l e s l i v e . R e q u i r e d f o r t a g w r i t i n g , s t r e a m i n g , a n d f i l e d e t e c t i o n w h e n y o u r m e d i a s e r v e r s t o r e s f i l e s a t a d i f f e r e n t p a t h t h a n S o u l S y n c c a n s e e . D o c k e r u s e r s : m o u n t y o u r m u s i c f o l d e r ( s ) w i t h r e a d - w r i t e a c c e s s , t h e n a d d t h e c o n t a i n e r - s i d e p a t h . < / l i >
< li > < strong > Replace Lower Quality on Import < / s t r o n g > & m d a s h ; O p t - i n t o g g l e i n S e t t i n g s & g t ; L i b r a r y . W h e n i m p o r t i n g f r o m S t a g i n g , i f a t r a c k a l r e a d y e x i s t s a t l o w e r q u a l i t y ( e . g . M P 3 ) , i t g e t s r e p l a c e d w i t h t h e h i g h e r q u a l i t y v e r s i o n ( e . g . F L A C ) . D i s a b l e d b y d e f a u l t . < / l i >
@ -1541,6 +1541,100 @@ const DOCS_SECTIONS = [
< / d i v >
`
} ,
{
id : 'troubleshooting' ,
title : 'Troubleshooting' ,
icon : '/static/settings.jpg' ,
children : [
{ id : 'ts-logs' , title : 'Understanding Logs' } ,
{ id : 'ts-debug' , title : 'Copy Debug Info' } ,
{ id : 'ts-common' , title : 'Common Issues' } ,
{ id : 'ts-reporting' , title : 'Reporting Issues' }
] ,
content : ( ) => `
< div class = "docs-subsection" id = "ts-logs" >
< h3 class = "docs-subsection-title" > Understanding Logs < / h 3 >
< p class = "docs-text" > SoulSync writes several log files that are critical for diagnosing issues . All logs are in the < code > logs / < / c o d e > d i r e c t o r y ( D o c k e r : < c o d e > / a p p / l o g s / < / c o d e > ) . < / p >
< table class = "docs-table" >
< thead > < tr > < th > File < / t h > < t h > W h a t I t C o n t a i n s < / t h > < t h > W h e n t o C h e c k < / t h > < / t r > < / t h e a d >
< tbody >
< tr > < td > < code > app . log < / c o d e > < / t d > < t d > M a i n a p p l i c a t i o n l o g & m d a s h ; A P I c a l l s , d o w n l o a d s , l i b r a r y s c a n s , e n r i c h m e n t , e r r o r s < / t d > < t d > F i r s t p l a c e t o l o o k f o r a n y i s s u e < / t d > < / t r >
< tr > < td > < code > post _processing . log < / c o d e > < / t d > < t d > F i l e p r o c e s s i n g p i p e l i n e & m d a s h ; t a g g i n g , o r g a n i z a t i o n , c o n v e r s i o n , f i l e m o v e s < / t d > < t d > F i l e s n o t a p p e a r i n g i n l i b r a r y , w r o n g t a g s , c o n v e r s i o n f a i l u r e s < / t d > < / t r >
< tr > < td > < code > acoustid . log < / c o d e > < / t d > < t d > A u d i o f i n g e r p r i n t v e r i f i c a t i o n r e s u l t s < / t d > < t d > W r o n g t r a c k s b e i n g d o w n l o a d e d , v e r i f i c a t i o n f a i l u r e s < / t d > < / t r >
< tr > < td > < code > source _reuse . log < / c o d e > < / t d > < t d > S o u l s e e k s o u r c e r e u s e d e c i s i o n s f o r a l b u m c o n s i s t e n c y < / t d > < t d > A l b u m s d o w n l o a d i n g f r o m m i x e d s o u r c e s < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< h4 > Setting Log Level < / h 4 >
< p class = "docs-text" > Go to < strong > Settings & rarr ; Advanced & rarr ; Logging < / s t r o n g > a n d c h a n g e t h e l o g l e v e l : < / p >
< ul class = "docs-list" >
< li > < strong > DEBUG < / s t r o n g > & m d a s h ; M a x i m u m d e t a i l . U s e t h i s w h e n t r o u b l e s h o o t i n g & m d a s h ; s h o w s e v e r y d e c i s i o n t h e a p p m a k e s < / l i >
< li > < strong > INFO < / s t r o n g > & m d a s h ; N o r m a l o p e r a t i o n s ( d e f a u l t ) . G o o d f o r d a y - t o - d a y u s e < / l i >
< li > < strong > WARNING < / s t r o n g > & m d a s h ; O n l y p r o b l e m s a n d u n u s u a l s i t u a t i o n s < / l i >
< li > < strong > ERROR < / s t r o n g > & m d a s h ; O n l y f a i l u r e s . M i n i m a l o u t p u t < / l i >
< / u l >
< div class = "docs-callout tip" > < span class = "docs-callout-icon" > & # x1F4A1 ; < / s p a n > < d i v > < s t r o n g > R e p r o d u c i n g a b u g ? < / s t r o n g > S e t l o g l e v e l t o < s t r o n g > D E B U G < / s t r o n g > , r e p r o d u c e t h e i s s u e , t h e n g r a b t h e l o g s . T h e e x t r a d e t a i l m a k e s i t m u c h e a s i e r t o i d e n t i f y t h e p r o b l e m . < / d i v > < / d i v >
< / d i v >
< div class = "docs-subsection" id = "ts-debug" >
< h3 class = "docs-subsection-title" > Copy Debug Info < / h 3 >
< p class = "docs-text" > The < strong > Copy Debug Info < / s t r o n g > b u t t o n i n t h e s i d e b a r c o l l e c t s a c o m p l e t e s n a p s h o t o f y o u r S o u l S y n c i n s t a n c e i n o n e c l i c k : < / p >
< ul class = "docs-list" >
< li > System info ( version , OS , Python , uptime , memory , CPU ) < / l i >
< li > Service connection status ( Spotify , Soulseek , Tidal , Qobuz , Discogs , media server ) < / l i >
< li > Library stats and database size < / l i >
< li > All configured paths with accessibility checks < / l i >
< li > Config settings ( download source , quality profile , post - processing , etc . ) < / l i >
< li > Enrichment worker status < / l i >
< li > API rate usage and any active rate limits < / l i >
< li > Recent log lines from the selected log file < / l i >
< / u l >
< p class = "docs-text" > Use the dropdowns to choose how many log lines to include ( 20 & ndash ; 500 ) and which log file to pull from . < / p >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v > D e b u g i n f o d o e s < s t r o n g > n o t < / s t r o n g > i n c l u d e A P I k e y s , t o k e n s , o r p a s s w o r d s & m d a s h ; i t i s s a f e t o s h a r e p u b l i c l y . < / d i v > < / d i v >
< / d i v >
< div class = "docs-subsection" id = "ts-common" >
< h3 class = "docs-subsection-title" > Common Issues < / h 3 >
< h4 > Downloads complete but tracks don ' t appear in library < / h 4 >
< ul class = "docs-list" >
< li > Check that your < strong > Transfer path < / s t r o n g > i s c o r r e c t a n d w r i t a b l e ( s e e P a t h s i n d e b u g i n f o ) < / l i >
< li > If using a media server , trigger a library scan after downloads complete < / l i >
< li > Check < code > post _processing . log < / c o d e > f o r f i l e m o v e e r r o r s < / l i >
< / u l >
< h4 > Soulseek search returns no results < / h 4 >
< ul class = "docs-list" >
< li > Verify slskd is running and the API key is correct in Settings < / l i >
< li > Check that slskd shows as connected on the Dashboard < / l i >
< li > Try searching directly in the slskd web UI to rule out network issues < / l i >
< / u l >
< h4 > Spotify shows "Rate Limited" < / h 4 >
< ul class = "docs-list" >
< li > This is temporary & mdash ; Spotify throttles API calls when limits are hit < / l i >
< li > SoulSync automatically falls back to other metadata sources during a ban < / l i >
< li > The rate limit modal shows a countdown . Enrichment workers auto - pause and resume when the ban lifts < / l i >
< / u l >
< h4 > Docker : paths not found / permission denied < / h 4 >
< ul class = "docs-list" >
< li > Paths in Settings must be < strong > container paths < / s t r o n g > ( e . g . < c o d e > / a p p / d o w n l o a d s < / c o d e > ) , n o t h o s t p a t h s < / l i >
< li > Ensure your Docker volume mounts match the container paths < / l i >
< li > Set PUID / PGID to match your host user ( Unraid default : 99 / 100 ) < / l i >
< / u l >
< h4 > Wrong track downloaded < / h 4 >
< ul class = "docs-list" >
< li > Enable < strong > AcoustID verification < / s t r o n g > i n S e t t i n g s t o c a t c h m i s m a t c h e s < / l i >
< li > Check < code > acoustid . log < / c o d e > f o r f i n g e r p r i n t c o m p a r i s o n d e t a i l s < / l i >
< li > Use the track redownload feature to try a different source < / l i >
< / u l >
< / d i v >
< div class = "docs-subsection" id = "ts-reporting" >
< h3 class = "docs-subsection-title" > Reporting Issues < / h 3 >
< p class = "docs-text" > When reporting a bug on < a href = "https://github.com/Nezreka/SoulSync/issues" target = "_blank" > GitHub Issues < /a> or in the <a href="https:/ / discord . gg / wGvKqVQwmy " target=" _blank " > Discord < / a > , i n c l u d e : < / p >
< ol class = "docs-list" >
< li > < strong > Debug info snapshot < / s t r o n g > & m d a s h ; C l i c k < s t r o n g > C o p y D e b u g I n f o < / s t r o n g > i n t h e H e l p s i d e b a r a n d p a s t e t h e o u t p u t < / l i >
< li > < strong > Steps to reproduce < / s t r o n g > & m d a s h ; W h a t y o u d i d , w h a t y o u e x p e c t e d , w h a t h a p p e n e d i n s t e a d < / l i >
< li > < strong > Relevant log lines < / s t r o n g > & m d a s h ; S e t l o g l e v e l t o D E B U G , r e p r o d u c e t h e i s s u e , a n d i n c l u d e t h e r e l e v a n t l o g s e c t i o n . T h e d e b u g i n f o i n c l u d e s r e c e n t l i n e s , b u t f o r l o n g e r i s s u e s y o u m a y n e e d t o p u l l f r o m t h e f u l l l o g f i l e < / l i >
< / o l >
< div class = "docs-callout tip" > < span class = "docs-callout-icon" > & # x1F4A1 ; < / s p a n > < d i v > < s t r o n g > T h e m o r e c o n t e x t y o u p r o v i d e , t h e f a s t e r t h e f i x . < / s t r o n g > A d e b u g i n f o s n a p s h o t + s t e p s t o r e p r o d u c e + D E B U G l o g e x c e r p t i s t h e i d e a l b u g r e p o r t . E v e n i f y o u t h i n k y o u k n o w t h e c a u s e , t h e l o g s o f t e n r e v e a l s o m e t h i n g u n e x p e c t e d . < / d i v > < / d i v >
< / d i v >
`
} ,
{
id : 'api' ,
title : 'REST API' ,
@ -2376,6 +2470,8 @@ function initializeDocsPage() {
text += ` Version: ${ data . version } \n ` ;
text += ` OS: ${ data . os } ${ data . docker ? ' (Docker)' : '' } \n ` ;
text += ` Python: ${ data . python } \n ` ;
text += ` ffmpeg: ${ data . ffmpeg || 'unknown' } \n ` ;
text += ` Runner: ${ data . runner || 'unknown' } \n ` ;
text += ` Uptime: ${ data . uptime || 'unknown' } \n ` ;
text += ` Memory: ${ data . memory _usage || '?' } (system: ${ data . system _memory || '?' } ) \n ` ;
text += ` CPU: ${ data . cpu _percent || '?' } \n ` ;
@ -2388,6 +2484,7 @@ function initializeDocsPage() {
text += ` Soulseek: ${ data . services ? . soulseek _connected ? ck + ' Connected' : ex + ' Disconnected' } \n ` ;
text += ` Tidal: ${ data . services ? . tidal _connected ? ck + ' Connected' : ex + ' Disconnected' } \n ` ;
text += ` Qobuz: ${ data . services ? . qobuz _connected ? ck + ' Connected' : ex + ' Disconnected' } \n ` ;
text += ` Discogs: ${ data . services ? . discogs _connected ? ck + ' Connected' : ex + ' No Token' } \n ` ;
text += ` Download Mode: ${ data . services ? . download _source || 'unknown' } \n \n ` ;
text += '── Library ──\n' ;
@ -2396,6 +2493,7 @@ function initializeDocsPage() {
text += ` Tracks: ${ data . library ? . tracks ? . toLocaleString ( ) || '0' } \n ` ;
text += ` Database: ${ data . database _size || 'unknown' } \n ` ;
text += ` Watchlist: ${ data . watchlist _count || 0 } artists \n ` ;
text += ` Wishlist: ${ data . wishlist _count || 0 } pending \n ` ;
text += ` Automations: ${ data . automations ? . enabled || 0 } enabled / ${ data . automations ? . total || 0 } total \n \n ` ;
text += '── Active ──\n' ;
@ -2406,16 +2504,37 @@ function initializeDocsPage() {
const pathStatus = ( exists , writable ) => exists ? ( writable ? ck + ' ok' : ck + ' exists ' + ex + ' not writable' ) : ex + ' missing' ;
text += ` Download: ${ data . paths ? . download _path || '(not set)' } [ ${ pathStatus ( data . paths ? . download _path _exists , data . paths ? . download _path _writable ) } ] \n ` ;
text += ` Transfer: ${ data . paths ? . transfer _folder || '(not set)' } [ ${ pathStatus ( data . paths ? . transfer _folder _exists , data . paths ? . transfer _folder _writable ) } ] \n ` ;
text += ` Staging: ${ data . paths ? . staging _folder || '(not set)' } [ ${ data . paths ? . staging _folder _exists ? ck + ' ok' : ex + ' missing' } ] \n \n ` ;
text += ` Staging: ${ data . paths ? . staging _folder ? data . paths . staging _folder + ' [' + ( data . paths . staging _folder _exists ? ck + ' ok' : ex + ' missing' ) + ']' : '(not configured — optional)' } \n ` ;
if ( data . paths ? . music _videos _path ) {
text += ` Videos: ${ data . paths . music _videos _path } [ ${ data . paths . music _videos _path _exists ? ck + ' ok' : ex + ' missing' } ] \n ` ;
}
if ( data . paths ? . music _library _paths ? . length ) {
text += ` Library Paths: \n ` ;
data . paths . music _library _paths . forEach ( p => {
text += ` ${ p . path } [ ${ p . exists ? ck + ' ok' : ex + ' missing' } ] \n ` ;
} ) ;
}
text += '\n' ;
text += '── Config ──\n' ;
if ( data . config ) {
text += ` Log Level: ${ data . config . log _level || 'INFO' } \n ` ;
text += ` Source Mode: ${ data . config . source _mode || 'unknown' } \n ` ;
if ( data . config . source _mode === 'hybrid' && data . config . hybrid _sources ? . length ) {
text += ` Hybrid Priority: ${ data . config . hybrid _sources . join ( ' → ' ) } \n ` ;
}
text += ` Metadata Source: ${ data . config . primary _metadata _source || 'deezer' } \n ` ;
text += ` Quality Profile: ${ data . config . quality _profile || 'default' } \n ` ;
text += ` Folder Template: ${ data . config . organization _template || '(default)' } \n ` ;
text += ` Post-Processing: ${ data . config . post _processing _enabled ? 'enabled' : 'disabled' } \n ` ;
if ( data . config . lossy _copy _enabled ) {
text += ` Lossy Copy: ${ data . config . lossy _copy _format ? . toUpperCase ( ) } @ ${ data . config . lossy _copy _bitrate } kbps \n ` ;
}
text += ` AcoustID: ${ data . config . acoustid _enabled ? 'enabled' : 'disabled' } \n ` ;
text += ` Auto Scan: ${ data . config . auto _scan _enabled ? 'enabled' : 'disabled' } \n ` ;
text += ` Auto Import: ${ data . config . auto _import _enabled ? 'enabled' : 'disabled' } \n ` ;
text += ` Duplicate Tracks: ${ data . config . allow _duplicate _tracks ? 'allowed' : 'rejected' } \n ` ;
text += ` Replace Quality: ${ data . config . replace _lower _quality ? 'enabled' : 'disabled' } \n ` ;
text += ` M3U Export: ${ data . config . m3u _export _enabled ? 'enabled' : 'disabled' } \n ` ;
}
text += '\n' ;
@ -2460,12 +2579,21 @@ function initializeDocsPage() {
}
text += '\n' ;
if ( data . available _logs ? . length ) {
text += '── Log Files ──\n' ;
data . available _logs . forEach ( log => {
text += ` ${ log . file . padEnd ( 24 ) } ${ log . size } \n ` ;
} ) ;
text += '\n' ;
}
text += ` ── Logs: ${ data . log _source || 'app' } .log (last ${ data . recent _logs ? . length || 0 } lines) ── \n ` ;
if ( data . recent _logs ? . length ) {
data . recent _logs . forEach ( line => { text += line + '\n' ; } ) ;
} else {
text += '(no log lines)\n' ;
}
text += '\n---\nPaste this output into your GitHub issue at https://github.com/Nezreka/SoulSync/issues\n' ;
// Copy to clipboard — navigator.clipboard requires HTTPS/localhost,
// so fall back to execCommand for Docker/LAN HTTP access
Broque Thomas
4 weeks ago