@ -12,6 +12,7 @@ const DOCS_SECTIONS = [
{ id : 'gs-first-setup' , title : 'First-Time Setup' } ,
{ id : 'gs-connecting' , title : 'Connecting Services' } ,
{ id : 'gs-interface' , title : 'Understanding the Interface' } ,
{ id : 'gs-folders' , title : 'Folder Setup (Downloads & Transfer)' } ,
{ id : 'gs-docker' , title : 'Docker & Deployment' }
] ,
content : ( ) => `
@ -75,6 +76,181 @@ const DOCS_SECTIONS = [
< / u l >
< p class = "docs-text" > < strong > Version & Updates < / s t r o n g > : C l i c k t h e v e r s i o n n u m b e r i n t h e s i d e b a r f o o t e r t o o p e n t h e < s t r o n g > W h a t ' s N e w < / s t r o n g > m o d a l , w h i c h s h o w s d e t a i l e d r e l e a s e n o t e s f o r e v e r y f e a t u r e a n d f i x . S o u l S y n c a u t o m a t i c a l l y c h e c k s f o r u p d a t e s b y c o m p a r i n g y o u r r u n n i n g v e r s i o n a g a i n s t t h e l a t e s t G i t H u b c o m m i t . I f a n u p d a t e i s a v a i l a b l e , a b a n n e r a p p e a r s i n t h e m o d a l . D o c k e r u s e r s a r e n o t i f i e d w h e n a n e w i m a g e h a s b e e n p u s h e d t o t h e r e p o . < / p >
< / d i v >
< div class = "docs-subsection" id = "gs-folders" >
< h3 class = "docs-subsection-title" > Folder Setup ( Downloads & Transfer ) < / h 3 >
< p class = "docs-text" > SoulSync uses < strong > three folders < / s t r o n g > t o m a n a g e y o u r m u s i c f i l e s . < s t r o n g > M o s t s e t u p i s s u e s c o m e f r o m i n c o r r e c t f o l d e r c o n f i g u r a t i o n < / s t r o n g > & m d a s h ; e s p e c i a l l y i n D o c k e r . R e a d t h i s s e c t i o n c a r e f u l l y . < / p >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v >
< strong > Docker users & mdash ; there are TWO steps , not one ! < / s t r o n g > < b r > < b r >
< strong > Step 1 : < / s t r o n g > M a p y o u r v o l u m e s i n < c o d e > d o c k e r - c o m p o s e . y m l < / c o d e > & m d a s h ; t h i s m a k e s f o l d e r s < e m > a c c e s s i b l e < / e m > t o t h e c o n t a i n e r . < b r >
< strong > Step 2 : < / s t r o n g > C o n f i g u r e t h e p a t h s i n < s t r o n g > S o u l S y n c S e t t i n g s & r a r r ; D o w n l o a d S e t t i n g s < / s t r o n g > & m d a s h ; t h i s t e l l s t h e a p p < e m > w h e r e t o l o o k < / e m > . < b r > < b r >
Setting up docker - compose volumes alone is < strong > not enough < / s t r o n g > . Y o u m u s t a l s o c o n f i g u r e t h e a p p s e t t i n g s . I f y o u s k i p S t e p 2 , d o w n l o a d s w i l l c o m p l e t e b u t n o t h i n g w i l l t r a n s f e r , p o s t - p r o c e s s i n g w i l l f a i l s i l e n t l y , a n d t r a c k s w i l l r e - d o w n l o a d r e p e a t e d l y .
< / d i v > < / d i v >
< h4 > The Three Folders < / h 4 >
< table class = "docs-table" >
< thead > < tr > < th > Folder < / t h > < t h > D e f a u l t ( D o c k e r ) < / t h > < t h > P u r p o s e < / t h > < / t r > < / t h e a d >
< tbody >
< tr > < td > < strong > Download Path < / s t r o n g > < / t d > < t d > < c o d e > / a p p / d o w n l o a d s < / c o d e > < / t d > < t d > W h e r e s l s k d / Y o u T u b e / T i d a l i n i t i a l l y s a v e s d o w n l o a d e d f i l e s . T h i s i s a < s t r o n g > t e m p o r a r y s t a g i n g a r e a < / s t r o n g > & m d a s h ; f i l e s s h o u l d n o t s t a y h e r e p e r m a n e n t l y . < / t d > < / t r >
< tr > < td > < strong > Transfer Path < / s t r o n g > < / t d > < t d > < c o d e > / a p p / T r a n s f e r < / c o d e > < / t d > < t d > W h e r e p o s t - p r o c e s s e d f i l e s a r e m o v e d a f t e r t a g g i n g a n d r e n a m i n g . T h i s < s t r o n g > m u s t < / s t r o n g > b e t h e f o l d e r y o u r m e d i a s e r v e r ( P l e x / J e l l y f i n / N a v i d r o m e ) m o n i t o r s . < / t d > < / t r >
< tr > < td > < strong > Staging Path < / s t r o n g > < / t d > < t d > < c o d e > / a p p / S t a g i n g < / c o d e > < / t d > < t d > F o r t h e I m p o r t f e a t u r e o n l y . D r o p a u d i o f i l e s h e r e t o i m p o r t t h e m i n t o y o u r l i b r a r y v i a t h e I m p o r t p a g e . < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< h4 > How Files Flow < / h 4 >
< div class = "docs-callout info" > < span class = "docs-callout-icon" > & # x2139 ; & # xFE0F ; < / s p a n > < d i v >
< strong > The complete download - to - library pipeline : < / s t r o n g > < b r > < b r >
< strong > 1. < / s t r o n g > Y o u s e a r c h f o r m u s i c i n S o u l S y n c a n d c l i c k d o w n l o a d < b r >
< strong > 2. < / s t r o n g > S o u l S y n c t e l l s s l s k d t o d o w n l o a d t h e f i l e & r a r r ; s l s k d s a v e s i t t o i t s d o w n l o a d f o l d e r < b r >
< strong > 3. < / s t r o n g > S o u l S y n c d e t e c t s t h e c o m p l e t e d d o w n l o a d i n t h e < s t r o n g > D o w n l o a d P a t h < / s t r o n g > < b r >
< strong > 4. < / s t r o n g > P o s t - p r o c e s s i n g r u n s : A c o u s t I D v e r i f i c a t i o n & r a r r ; m e t a d a t a t a g g i n g & r a r r ; c o v e r a r t e m b e d d i n g & r a r r ; l y r i c s f e t c h < b r >
< strong > 5. < / s t r o n g > F i l e i s r e n a m e d a n d o r g a n i z e d ( e . g . , < c o d e > A r t i s t / A l b u m / 0 1 - T i t l e . f l a c < / c o d e > ) < b r >
< strong > 6. < / s t r o n g > F i l e i s m o v e d f r o m D o w n l o a d P a t h & r a r r ; < s t r o n g > T r a n s f e r P a t h < / s t r o n g > < b r >
< strong > 7. < / s t r o n g > M e d i a s e r v e r s c a n i s t r i g g e r e d & r a r r ; f i l e a p p e a r s i n y o u r l i b r a r y < b r > < b r >
< strong > If any step fails , the pipeline stops . < / s t r o n g > T h e m o s t c o m m o n f a i l u r e p o i n t i s S t e p 3 & m d a s h ; S o u l S y n c c a n ' t f i n d t h e f i l e b e c a u s e t h e D o w n l o a d P a t h d o e s n ' t m a t c h w h e r e s l s k d a c t u a l l y s a v e d i t .
< / d i v > < / d i v >
< h4 > Docker Setup : The Full Picture < / h 4 >
< p class = "docs-text" > In Docker , every app runs in its own isolated container with its own filesystem . < strong > Volume mounts < / s t r o n g > i n d o c k e r - c o m p o s e c r e a t e " b r i d g e s " b e t w e e n y o u r h o s t f o l d e r s a n d t h e c o n t a i n e r . B u t S o u l S y n c d o e s n ' t a u t o m a t i c a l l y k n o w w h e r e t h o s e b r i d g e s g o & m d a s h ; y o u h a v e t o t e l l i t v i a t h e S e t t i n g s p a g e . < / p >
< p class = "docs-text" > Here ' s what happens with a properly configured setup : < / p >
< div class = "docs-callout info" > < span class = "docs-callout-icon" > & # x1F5C2 ; & # xFE0F ; < / s p a n > < d i v >
< strong > HOST ( your server ) < / s t r o n g > < b r >
< code style = "color: var(--accent-primary);" > / m n t / d a t a / s l s k d - d o w n l o a d s / < / c o d e > & l a r r ; w h e r e s l s k d s a v e s f i l e s o n y o u r s e r v e r < b r >
< code style = "color: #50e050;" > / m n t / m e d i a / m u s i c / < / c o d e > & l a r r ; w h e r e P l e x / J e l l y f i n / N a v i d r o m e w a t c h e s < b r > < b r >
< strong > docker - compose . yml ( the bridges ) < / s t r o n g > < b r >
< code style = "color: var(--accent-primary);" > / m n t / d a t a / s l s k d - d o w n l o a d s < / c o d e > : < c o d e > / a p p / d o w n l o a d s < / c o d e > < b r >
< code style = "color: #50e050;" > / m n t / m e d i a / m u s i c < / c o d e > : < c o d e > / a p p / T r a n s f e r < / c o d e > < b r > < b r >
< strong > CONTAINER ( what SoulSync sees ) < / s t r o n g > < b r >
< code > / a p p / d o w n l o a d s / < / c o d e > & l a r r ; s a m e f i l e s a s < c o d e s t y l e = " c o l o r : v a r ( - - a c c e n t - p r i m a r y ) ; " > / m n t / d a t a / s l s k d - d o w n l o a d s / < / c o d e > < b r >
< code > / a p p / T r a n s f e r / < / c o d e > & l a r r ; s a m e f i l e s a s < c o d e s t y l e = " c o l o r : # 5 0 e 0 5 0 ; " > / m n t / m e d i a / m u s i c / < / c o d e > < b r > < b r >
< strong > SoulSync Settings ( what you enter in the app ) < / s t r o n g > < b r >
Download Path : < code > / a p p / d o w n l o a d s < / c o d e > < b r >
Transfer Path : < code > / a p p / T r a n s f e r < / c o d e >
< / d i v > < / d i v >
< h4 > The # 1 Mistake : Not Configuring App Settings < / h 4 >
< p class = "docs-text" > Many users set up their docker - compose volumes correctly but < strong > never open SoulSync Settings to configure the paths < / s t r o n g > . T h e a p p d e f a u l t s m a y n o t m a t c h y o u r v o l u m e m o u n t s . Y o u m u s t g o t o < s t r o n g > S e t t i n g s & r a r r ; D o w n l o a d S e t t i n g s < / s t r o n g > a n d v e r i f y t h a t : < / p >
< ul class = "docs-list" >
< li > < strong > Download Path < / s t r o n g > m a t c h e s w h e r e s l s k d p u t s c o m p l e t e d f i l e s < e m > i n s i d e t h e c o n t a i n e r < / e m > ( u s u a l l y < c o d e > / a p p / d o w n l o a d s < / c o d e > ) < / l i >
< li > < strong > Transfer Path < / s t r o n g > m a t c h e s w h e r e y o u m o u n t e d y o u r m e d i a l i b r a r y < e m > i n s i d e t h e c o n t a i n e r < / e m > ( u s u a l l y < c o d e > / a p p / T r a n s f e r < / c o d e > ) < / l i >
< / u l >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v >
< strong > "I set up my docker-compose but nothing transfers" < / s t r o n g > & m d a s h ; t h i s a l m o s t a l w a y s m e a n s t h e a p p s e t t i n g s w e r e n ' t c o n f i g u r e d . D o c k e r - c o m p o s e m a k e s t h e f o l d e r s a c c e s s i b l e . T h e a p p s e t t i n g s t e l l S o u l S y n c w h e r e t o l o o k . < s t r o n g > B o t h a r e r e q u i r e d . < / s t r o n g >
< / d i v > < / d i v >
< h4 > The # 2 Mistake : Download Path Doesn ' t Match slskd < / h 4 >
< p class = "docs-text" > The < strong > Download Path < / s t r o n g > i n S o u l S y n c m u s t p o i n t t o t h e < s t r o n g > e x a c t s a m e p h y s i c a l f o l d e r < / s t r o n g > w h e r e s l s k d s a v e s i t s c o m p l e t e d d o w n l o a d s . I f t h e y d o n ' t m a t c h , S o u l S y n c c a n ' t f i n d t h e f i l e s a n d p o s t - p r o c e s s i n g f a i l s s i l e n t l y . < / p >
< div class = "docs-callout info" > < span class = "docs-callout-icon" > & # x2139 ; & # xFE0F ; < / s p a n > < d i v >
< strong > Both SoulSync and slskd must see the same download folder . < / s t r o n g > < b r > < b r >
< strong > slskd container : < / s t r o n g > < b r >
& bull ; slskd downloads to < code > / d o w n l o a d s / c o m p l e t e < / c o d e > i n s i d e i t s o w n c o n t a i n e r < b r >
& bull ; slskd docker - compose : < code > - / m n t / d a t a / s l s k d - d o w n l o a d s : / d o w n l o a d s / c o m p l e t e < / c o d e > < b r > < b r >
< strong > SoulSync container : < / s t r o n g > < b r >
& bull ; SoulSync docker - compose : < code > - / m n t / d a t a / s l s k d - d o w n l o a d s : / a p p / d o w n l o a d s < / c o d e > ( s a m e h o s t f o l d e r ! ) < b r >
& bull ; SoulSync Setting : Download Path = < code > / a p p / d o w n l o a d s < / c o d e > < b r > < b r >
< strong > The key : < / s t r o n g > b o t h c o n t a i n e r s m o u n t t h e < s t r o n g > s a m e h o s t f o l d e r < / s t r o n g > ( < c o d e > / m n t / d a t a / s l s k d - d o w n l o a d s < / c o d e > ) . T h e c o n t a i n e r - i n t e r n a l p a t h s c a n b e d i f f e r e n t & m d a s h ; t h a t ' s f i n e . W h a t m a t t e r s i s t h e y p o i n t t o t h e s a m e p h y s i c a l d i r e c t o r y o n y o u r s e r v e r .
< / d i v > < / d i v >
< h4 > The # 3 Mistake : Using Host Paths in Settings < / h 4 >
< p class = "docs-text" > If you 're running in Docker, the paths you enter in SoulSync' s Settings page must be < strong > container - side paths < / s t r o n g > ( t h e r i g h t s i d e o f t h e < c o d e > : < / c o d e > i n y o u r v o l u m e m o u n t ) , < s t r o n g > n o t < / s t r o n g > h o s t p a t h s ( t h e l e f t s i d e ) . S o u l S y n c r u n s i n s i d e t h e c o n t a i n e r a n d c a n o n l y s e e i t s o w n f i l e s y s t e m . < / p >
< table class = "docs-table" >
< thead > < tr > < th > < / t h > < t h > S e t t i n g V a l u e < / t h > < t h > R e s u l t < / t h > < / t r > < / t h e a d >
< tbody >
< tr > < td > & # x2705 ; < / t d > < t d > < c o d e > / a p p / d o w n l o a d s < / c o d e > < / t d > < t d > C o r r e c t & m d a s h ; t h i s i s t h e c o n t a i n e r - s i d e p a t h ( r i g h t s i d e o f < c o d e > : < / c o d e > ) < / t d > < / t r >
< tr > < td > & # x2705 ; < / t d > < t d > < c o d e > / a p p / T r a n s f e r < / c o d e > < / t d > < t d > C o r r e c t & m d a s h ; t h i s i s t h e c o n t a i n e r - s i d e p a t h ( r i g h t s i d e o f < c o d e > : < / c o d e > ) < / t d > < / t r >
< tr > < td > & # x274C ; < / t d > < t d > < c o d e > / m n t / d a t a / s l s k d - d o w n l o a d s < / c o d e > < / t d > < t d > W r o n g & m d a s h ; t h i s i s t h e h o s t p a t h ( l e f t s i d e o f < c o d e > : < / c o d e > ) , d o e s n ' t e x i s t i n s i d e t h e c o n t a i n e r < / t d > < / t r >
< tr > < td > & # x274C ; < / t d > < t d > < c o d e > / m n t / m u s i c < / c o d e > < / t d > < t d > W r o n g & m d a s h ; h o s t p a t h , t h e c o n t a i n e r c a n ' t s e e t h i s < / t d > < / t r >
< tr > < td > & # x274C ; < / t d > < t d > < c o d e > . / d o w n l o a d s < / c o d e > < / t d > < t d > W r o n g & m d a s h ; r e l a t i v e p a t h , u s e t h e f u l l c o n t a i n e r p a t h < c o d e > / a p p / d o w n l o a d s < / c o d e > < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< h4 > Transfer Path = Media Server ' s Music Folder < / h 4 >
< p class = "docs-text" > Your Transfer Path must ultimately point to the same physical directory your media server monitors . This is how new music appears in Plex / Jellyfin / Navidrome . < / p >
< div class = "docs-callout tip" > < span class = "docs-callout-icon" > & # x1F4A1 ; < / s p a n > < d i v >
< strong > Example with Plex : < / s t r o n g > < b r > < b r >
& bull ; Plex monitors < code > / m n t / m e d i a / m u s i c < / c o d e > o n t h e h o s t < b r >
& bull ; SoulSync docker - compose : < code > - / m n t / m e d i a / m u s i c : / a p p / T r a n s f e r : r w < / c o d e > < b r >
& bull ; SoulSync Settings : Transfer Path = < code > / a p p / T r a n s f e r < / c o d e > < b r > < b r >
< strong > Result : < / s t r o n g > S o u l S y n c w r i t e s t o < c o d e > / a p p / T r a n s f e r < / c o d e > i n s i d e t h e c o n t a i n e r & r a r r ; a p p e a r s a t < c o d e > / m n t / m e d i a / m u s i c < / c o d e > o n t h e h o s t & r a r r ; P l e x s e e s i t a n d a d d s i t t o y o u r l i b r a r y .
< / d i v > < / d i v >
< h4 > Complete Docker Compose Example ( slskd + SoulSync ) < / h 4 >
< p class = "docs-text" > Here ' s a working example showing both slskd and SoulSync configured to share the same download folder : < / p >
< div class = "docs-callout info" > < span class = "docs-callout-icon" > & # x1F4CB ; < / s p a n > < d i v >
< code > < strong > # docker - compose . yml < / s t r o n g > < / c o d e > < b r >
< code > services : < / c o d e > < b r >
< code > & nbsp ; & nbsp ; slskd : < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; image : slskd / slskd : latest < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; volumes : < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; < span style = "color: var(--accent-primary);" > # slskd saves completed downloads here < / s p a n > < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / m n t / d a t a / s l s k d - d o w n l o a d s : / d o w n l o a d s < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / d o c k e r / s l s k d / c o n f i g : / a p p < / c o d e > < b r > < b r >
< code > & nbsp ; & nbsp ; soulsync : < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; image : boulderbadgedad / soulsync : latest < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; volumes : < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; < span style = "color: var(--accent-primary);" > # SAME host folder as slskd & mdash ; this is the key ! < / s p a n > < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / m n t / d a t a / s l s k d - d o w n l o a d s : / a p p / d o w n l o a d s < / c o d e > < b r > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; < span style = "color: #50e050;" > # Your media server ' s music folder < / s p a n > < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / m n t / m e d i a / m u s i c : / a p p / T r a n s f e r : r w < / c o d e > < b r > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; < span style = "color: #888;" > # Config , logs , staging , database < / s p a n > < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / d o c k e r / s o u l s y n c / c o n f i g : / a p p / c o n f i g < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / d o c k e r / s o u l s y n c / l o g s : / a p p / l o g s < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - / d o c k e r / s o u l s y n c / s t a g i n g : / a p p / S t a g i n g < / c o d e > < b r >
< code > & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; & nbsp ; - soulsync _database : / a p p / d a t a < / c o d e > < b r > < b r >
< code > < strong > # Then in SoulSync Settings : < / s t r o n g > < / c o d e > < b r >
< code > # Download Path : / a p p / d o w n l o a d s < / c o d e > < b r >
< code > # Transfer Path : / a p p / T r a n s f e r < / c o d e >
< / d i v > < / d i v >
< h4 > Setup Checklist < / h 4 >
< p class = "docs-text" > Go through every item . If you miss any single one , the pipeline will break : < / p >
< ol class = "docs-steps" >
< li > < strong > slskd download folder is mounted in SoulSync ' s container < / s t r o n g > & m d a s h ; B o t h c o n t a i n e r s m u s t m o u n t t h e < s t r o n g > s a m e h o s t d i r e c t o r y < / s t r o n g > . T h e h o s t p a t h s ( l e f t s i d e o f < c o d e > : < / c o d e > ) m u s t b e i d e n t i c a l . < / l i >
< li > < strong > Media server ' s music folder is mounted as Transfer < / s t r o n g > & m d a s h ; M o u n t t h e f o l d e r y o u r P l e x / J e l l y f i n / N a v i d r o m e m o n i t o r s a s < c o d e > / a p p / T r a n s f e r < / c o d e > w i t h < c o d e > : r w < / c o d e > p e r m i s s i o n s . < / l i >
< li > < strong > SoulSync Settings are configured < / s t r o n g > & m d a s h ; O p e n < s t r o n g > S e t t i n g s & r a r r ; D o w n l o a d S e t t i n g s < / s t r o n g > . S e t D o w n l o a d P a t h t o < c o d e > / a p p / d o w n l o a d s < / c o d e > a n d T r a n s f e r P a t h t o < c o d e > / a p p / T r a n s f e r < / c o d e > ( o r w h a t e v e r c o n t a i n e r p a t h s y o u u s e d o n t h e r i g h t s i d e o f < c o d e > : < / c o d e > ) . < / l i >
< li > < strong > slskd URL and API key are set < / s t r o n g > & m d a s h ; I n < s t r o n g > S e t t i n g s & r a r r ; S o u l s e e k < / s t r o n g > , e n t e r y o u r s l s k d U R L ( e . g . , < c o d e > h t t p : / / s l s k d : 5 0 3 0 < / c o d e > o r < c o d e > h t t p : / / h o s t . d o c k e r . i n t e r n a l : 5 0 3 0 < / c o d e > ) a n d A P I k e y . < / l i >
< li > < strong > PUID / PGID match your host user < / s t r o n g > & m d a s h ; R u n < c o d e > i d < / c o d e > o n y o u r h o s t . S e t t h o s e v a l u e s i n d o c k e r - c o m p o s e e n v i r o n m e n t v a r i a b l e s . B o t h s l s k d a n d S o u l S y n c s h o u l d u s e t h e s a m e P U I D / P G I D . < / l i >
< li > < strong > Test with one track < / s t r o n g > & m d a s h ; D o w n l o a d a s i n g l e t r a c k . W a t c h t h e l o g s . I f i t d o w n l o a d s b u t d o e s n ' t t r a n s f e r , t h e p a t h s a r e w r o n g . < / l i >
< / o l >
< h4 > Permissions < / h 4 >
< p class = "docs-text" > If paths are correct but files still won 't transfer, it' s usually a permissions issue . SoulSync needs < strong > read + write < / s t r o n g > a c c e s s t o a l l t h r e e f o l d e r s . < / p >
< ul class = "docs-list" >
< li > Set < code > PUID < / c o d e > a n d < c o d e > P G I D < / c o d e > i n y o u r d o c k e r - c o m p o s e t o m a t c h t h e u s e r t h a t o w n s y o u r m u s i c f o l d e r s ( r u n < c o d e > i d < / c o d e > o n y o u r h o s t t o f i n d y o u r U I D / G I D & m d a s h ; u s u a l l y 1 0 0 0 / 1 0 0 0 ) < / l i >
< li > Ensure the Transfer folder is writable : < code > chmod - R 755 / mnt / media / music < / c o d e > ( u s e y o u r a c t u a l h o s t p a t h ) < / l i >
< li > If using multiple containers ( slskd + SoulSync ) , both must use the < strong > same PUID / PGID < / s t r o n g > s o f i l e p e r m i s s i o n s a r e c o m p a t i b l e < / l i >
< li > NFS / CIFS / network mounts may need additional permissions & mdash ; test with a local folder first to isolate the issue < / l i >
< / u l >
< h4 > Verifying Your Setup < / h 4 >
< p class = "docs-text" > Run these commands to confirm everything is wired up correctly : < / p >
< ol class = "docs-steps" >
< li > < strong > Verify downloads are visible : < / s t r o n g > < c o d e > d o c k e r e x e c s o u l s y n c - w e b u i l s - l a / a p p / d o w n l o a d s < / c o d e > & m d a s h ; y o u s h o u l d s e e s l s k d ' s d o w n l o a d e d f i l e s h e r e . I f e m p t y o r " N o s u c h f i l e o r d i r e c t o r y " , y o u r v o l u m e m o u n t i s w r o n g . < / l i >
< li > < strong > Verify Transfer is writable : < / s t r o n g > < c o d e > d o c k e r e x e c s o u l s y n c - w e b u i t o u c h / a p p / T r a n s f e r / t e s t . t x t & & e c h o " O K " < / c o d e > & m d a s h ; t h e n c h e c k t h a t < c o d e > t e s t . t x t < / c o d e > a p p e a r s i n y o u r m e d i a s e r v e r ' s m u s i c f o l d e r o n t h e h o s t . C l e a n u p a f t e r : < c o d e > r m / m n t / m e d i a / m u s i c / t e s t . t x t < / c o d e > < / l i >
< li > < strong > Verify permissions : < / s t r o n g > < c o d e > d o c k e r e x e c s o u l s y n c - w e b u i i d < / c o d e > & m d a s h ; t h e u i d a n d g i d s h o u l d m a t c h y o u r P U I D / P G I D v a l u e s . < / l i >
< li > < strong > Verify app settings : < / s t r o n g > O p e n S o u l S y n c S e t t i n g s & r a r r ; D o w n l o a d S e t t i n g s . C o n f i r m t h e D o w n l o a d P a t h a n d T r a n s f e r P a t h s h o w c o n t a i n e r p a t h s ( l i k e < 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 > < strong > Test a single download : < / s t r o n g > S e a r c h f o r a t r a c k , d o w n l o a d i t , a n d w a t c h t h e l o g s . E n a b l e D E B U G l o g g i n g i n S e t t i n g s f o r f u l l d e t a i l . C h e c k < c o d e > l o g s / a p p . l o g < / c o d e > f o r a n y p a t h e r r o r s . < / l i >
< / o l >
< h4 > Troubleshooting < / h 4 >
< table class = "docs-table" >
< thead > < tr > < th > Symptom < / t h > < t h > L i k e l y C a u s e < / t h > < t h > F i x < / t h > < / t r > < / t h e a d >
< tbody >
< tr > < td > Files download but never transfer < / t d > < t d > A p p s e t t i n g s n o t c o n f i g u r e d & m d a s h ; d o c k e r - c o m p o s e v o l u m e s a r e s e t b u t S o u l S y n c S e t t i n g s s t i l l h a v e d e f a u l t s o r w r o n g p a t h s < / t d > < t d > O p e n < s t r o n g > S e t t i n g s & r a r r ; D o w n l o a d S e t t i n g s < / s t r o n g > a n d s e t D o w n l o a d P a t h + T r a n s f e r P a t h t o y o u r < s t r o n g > c o n t a i n e r - s i d e < / s t r o n g > m o u n t p a t h s . < / t d > < / t r >
< tr > < td > Post - processing log is empty < / t d > < t d > S o u l S y n c c a n ' t f i n d t h e d o w n l o a d e d f i l e a t t h e e x p e c t e d p a t h & m d a s h ; t h e D o w n l o a d P a t h i n S e t t i n g s d o e s n ' t m a t c h w h e r e s l s k d a c t u a l l y s a v e s f i l e s i n s i d e t h e c o n t a i n e r < / t d > < t d > R u n < c o d e > d o c k e r e x e c s o u l s y n c - w e b u i l s / a p p / d o w n l o a d s < / c o d e > t o s e e w h a t ' s a c t u a l l y t h e r e . T h e D o w n l o a d P a t h i n S e t t i n g s m u s t m a t c h t h i s p a t h e x a c t l y . < / t d > < / t r >
< tr > < td > Same tracks downloading multiple times < / t d > < t d > P o s t - p r o c e s s i n g f a i l s s o S o u l S y n c t h i n k s t h e t r a c k w a s n e v e r d o w n l o a d e d s u c c e s s f u l l y . O n r e s u m e , i t t r i e s a g a i n . < / t d > < t d > F i x t h e f o l d e r p a t h s f i r s t . O n c e p o s t - p r o c e s s i n g w o r k s , f i l e s m o v e t o T r a n s f e r a n d S o u l S y n c k n o w s t h e y e x i s t . < / t d > < / t r >
< tr > < td > Files not renamed properly < / t d > < t d > P o s t - p r o c e s s i n g i s n ' t r u n n i n g ( p a t h m i s m a t c h ) o r f i l e o r g a n i z a t i o n i s d i s a b l e d i n S e t t i n g s < / t d > < t d > V e r i f y F i l e O r g a n i z a t i o n i s e n a b l e d i n < s t r o n g > S e t t i n g s & r a r r ; P r o c e s s i n g & O r g a n i z a t i o n < / s t r o n g > . F i x D o w n l o a d P a t h f i r s t . < / t d > < / t r >
< tr > < td > Permission denied in logs < / t d > < t d > C o n t a i n e r u s e r c a n ' t w r i t e t o t h e T r a n s f e r f o l d e r o n t h e h o s t < / t d > < t d > S e t P U I D / P G I D t o m a t c h t h e h o s t u s e r t h a t o w n s t h e m u s i c f o l d e r . R u n < c o d e > c h m o d - R 7 5 5 < / c o d e > o n t h e T r a n s f e r h o s t f o l d e r . < / t d > < / t r >
< tr > < td > Media server doesn 't see new files</td><td>Transfer Path doesn' t map to the folder your media server monitors < / t d > < t d > E n s u r e t h e < s t r o n g > h o s t p a t h < / s t r o n g > i n y o u r S o u l S y n c v o l u m e m o u n t ( < c o d e > / m n t / m e d i a / m u s i c : / a p p / T r a n s f e r < / c o d e > ) i s t h e s a m e f o l d e r P l e x / J e l l y f i n / N a v i d r o m e w a t c h e s . < / t d > < / t r >
< tr > < td > slskd downloads work fine on their own but not through SoulSync < / t d > < t d > s l s k d ' s d o w n l o a d f o l d e r a n d S o u l S y n c ' s D o w n l o a d P a t h p o i n t t o d i f f e r e n t p h y s i c a l l o c a t i o n s < / t d > < t d > B o t h c o n t a i n e r s m u s t m o u n t t h e < s t r o n g > s a m e h o s t d i r e c t o r y < / s t r o n g > . C h e c k t h e l e f t s i d e o f < c o d e > : < / c o d e > i n b o t h d o c k e r - c o m p o s e v o l u m e e n t r i e s & m d a s h ; t h e y m u s t m a t c h . < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< div class = "docs-callout tip" > < span class = "docs-callout-icon" > & # x1F4A1 ; < / s p a n > < d i v > < s t r o n g > S t i l l s t u c k ? < / s t r o n g > E n a b l e D E B U G l o g g i n g i n S e t t i n g s , d o w n l o a d a s i n g l e t r a c k , a n d c h e c k < c o d e > l o g s / a p p . l o g < / c o d e > . T h e p o s t - p r o c e s s i n g l o g w i l l s h o w e x a c t l y w h e r e t h e f i l e p i p e l i n e b r e a k s & m d a s h ; w h e t h e r i t ' s a p a t h n o t f o u n d , p e r m i s s i o n d e n i e d , o r v e r i f i c a t i o n f a i l u r e . I f t h e p o s t - p r o c e s s i n g l o g i s e m p t y , t h e i s s u e i s a l m o s t c e r t a i n l y a p a t h m i s m a t c h ( S o u l S y n c n e v e r f o u n d t h e f i l e t o p r o c e s s ) . < / d i v > < / d i v >
< / d i v >
< div class = "docs-subsection" id = "gs-docker" >
< h3 class = "docs-subsection-title" > Docker & Deployment < / h 3 >
< p class = "docs-text" > SoulSync runs in Docker with the following environment variables : < / p >
@ -86,8 +262,21 @@ const DOCS_SECTIONS = [
< tr > < td > < code > SOULSYNC _COMMIT _SHA < / c o d e > < / t d > < t d > ( a u t o ) < / t d > < t d > B a k e d i n a t D o c k e r b u i l d t i m e . U s e d f o r u p d a t e d e t e c t i o n & m d a s h ; c o m p a r e s a g a i n s t G i t H u b ' s l a t e s t c o m m i t . < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< p class = "docs-text" > < strong > Key volume mounts < / s t r o n g > : M a p y o u r d o w n l o a d p a t h , t r a n s f e r p a t h ( m e d i a s e r v e r ' s m o n i t o r e d f o l d e r ) , a n d s t a g i n g p a t h t o h o s t d i r e c t o r i e s . E n s u r e t h e p a t h s c o n f i g u r e d i n S o u l S y n c S e t t i n g s m a t c h t h e c o n t a i n e r - s i d e m o u n t p o i n t s . < / p >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v > I f u s i n g s l s k d i n a s e p a r a t e c o n t a i n e r , m a k e s u r e b o t h c o n t a i n e r s c a n a c c e s s t h e s a m e d o w n l o a d d i r e c t o r y . A c o m m o n i s s u e i s s l s k d w r i t i n g t o a p a t h t h a t S o u l S y n c c a n ' t r e a d b e c a u s e t h e v o l u m e m o u n t s d o n ' t a l i g n . B o t h c o n t a i n e r s m u s t s e e t h e s a m e f i l e s a t t h e s a m e i n t e r n a l p a t h . < / d i v > < / d i v >
< h4 > Key Volume Mounts < / h 4 >
< p class = "docs-text" > Your docker - compose < code > volumes < / c o d e > s e c t i o n m u s t i n c l u d e t h e s e m a p p i n g s . T h e l e f t s i d e i s y o u r h o s t p a t h , t h e r i g h t s i d e i s w h e r e S o u l S y n c s e e s i t i n s i d e t h e c o n t a i n e r : < / p >
< table class = "docs-table" >
< thead > < tr > < th > Mount < / t h > < t h > C o n t a i n e r P a t h < / t h > < t h > W h a t G o e s H e r e < / t h > < / t r > < / t h e a d >
< tbody >
< tr > < td > slskd downloads < / t d > < t d > < c o d e > / a p p / d o w n l o a d s < / c o d e > < / t d > < t d > M u s t b e t h e s a m e p h y s i c a l f o l d e r s l s k d w r i t e s c o m p l e t e d d o w n l o a d s t o . B o t h c o n t a i n e r s m o u n t t h e s a m e h o s t d i r e c t o r y . < / t d > < / t r >
< tr > < td > Music library < / t d > < t d > < c o d e > / a p p / T r a n s f e r < / c o d e > < / t d > < t d > Y o u r m e d i a s e r v e r ' s m o n i t o r e d m u s i c f o l d e r . A d d < c o d e > : r w < / c o d e > t o e n s u r e w r i t e a c c e s s . < / t d > < / t r >
< tr > < td > Staging < / t d > < t d > < c o d e > / a p p / S t a g i n g < / c o d e > < / t d > < t d > ( O p t i o n a l ) F o r t h e I m p o r t f e a t u r e & m d a s h ; d r o p f i l e s h e r e t o i m p o r t t h e m . < / t d > < / t r >
< tr > < td > Config < / t d > < t d > < c o d e > / a p p / c o n f i g < / c o d e > < / t d > < t d > S t o r e s < c o d e > c o n f i g . j s o n < / c o d e > a n d e n c r y p t i o n k e y . P e r s i s t s s e t t i n g s a c r o s s r e s t a r t s . < / t d > < / t r >
< tr > < td > Logs < / t d > < t d > < c o d e > / a p p / l o g s < / c o d e > < / t d > < t d > A p p l i c a t i o n l o g s i n c l u d i n g < c o d e > a p p . l o g < / c o d e > a n d < c o d e > p o s t - p r o c e s s i n g . l o g < / c o d e > . < / t d > < / t r >
< tr > < td > Database < / t d > < t d > < c o d e > / a p p / d a t a < / c o d e > < / t d > < t d > < s t r o n g > M u s t u s e a n a m e d v o l u m e < / s t r o n g > ( n o t a h o s t p a t h ) . H o s t p a t h m o u n t s c a n c a u s e d a t a b a s e c o r r u p t i o n . < / t d > < / t r >
< / t b o d y >
< / t a b l e >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v > < s t r o n g > s l s k d + S o u l S y n c s h a r e d d o w n l o a d s : < / s t r o n g > I f s l s k d r u n s i n a s e p a r a t e c o n t a i n e r , b o t h c o n t a i n e r s m u s t m o u n t t h e < s t r o n g > s a m e h o s t d i r e c t o r y < / s t r o n g > f o r d o w n l o a d s . A c o m m o n i s s u e i s s l s k d w r i t i n g t o a p a t h t h a t S o u l S y n c c a n ' t r e a d b e c a u s e t h e v o l u m e m o u n t s d o n ' t a l i g n . B o t h c o n t a i n e r s m u s t s e e t h e s a m e f i l e s . S e e t h e < s t r o n g > F o l d e r S e t u p < / s t r o n g > s e c t i o n a b o v e f o r d e t a i l e d e x a m p l e s . < / d i v > < / d i v >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v > < s t r o n g > D a t a b a s e v o l u m e : < / s t r o n g > A l w a y s u s e a n a m e d v o l u m e f o r t h e d a t a b a s e ( < c o d e > s o u l s y n c _ d a t a b a s e : / a p p / d a t a < / c o d e > ) , n e v e r a h o s t p a t h m o u n t . H o s t p a t h m o u n t s c a n c a u s e S Q L i t e c o r r u p t i o n , e s p e c i a l l y o n n e t w o r k e d f i l e s y s t e m s o r w h e n p e r m i s s i o n s d o n ' t a l i g n . < / d i v > < / d i v >
< p class = "docs-text" > < strong > Podman / Rootless Docker < / s t r o n g > : S o u l S y n c s u p p o r t s P o d m a n r o o t l e s s ( k e e p - i d ) a n d r o o t l e s s D o c k e r s e t u p s . T h e e n t r y p o i n t h a n d l e s p e r m i s s i o n a l i g n m e n t a u t o m a t i c a l l y . < / p >
< p class = "docs-text" > < strong > Config migration < / s t r o n g > : W h e n u p g r a d i n g f r o m o l d e r v e r s i o n s , S o u l S y n c a u t o m a t i c a l l y m i g r a t e s s e t t i n g s f r o m < c o d e > c o n f i g . j s o n < / c o d e > t o t h e d a t a b a s e o n f i r s t s t a r t u p . N o m a n u a l m i g r a t i o n i s n e e d e d . < / p >
< / d i v >
@ -840,13 +1029,14 @@ const DOCS_SECTIONS = [
< h3 class = "docs-subsection-title" > Download Settings < / h 3 >
< ul class = "docs-list" >
< li > < strong > Download Source Mode < / s t r o n g > & m d a s h ; S o u l s e e k , Y o u T u b e , T i d a l , o r H y b r i d . H y b r i d t r i e s y o u r p r i m a r y s o u r c e f i r s t , t h e n f a l l s b a c k t o a l t e r n a t e s . S e e < e m > D o w n l o a d S o u r c e s < / e m > i n t h e M u s i c D o w n l o a d s s e c t i o n f o r d e t a i l s . < / l i >
< li > < strong > Download Path < / s t r o n g > & m d a s h ; W h e r e f i l e s a r e i n i t i a l l y d o w n l o a d e d a n d p r o c e s s e d < / l i >
< li > < strong > Transfer Path < / s t r o n g > & m d a s h ; Wh e r e p r o c e s s e d f i l e s a r e m o v e d a f t e r t a g g i n g a n d o r g a n i z at i o n . S h o u l d p o i n t t o y o u r m e d i a s e r v e r ' s m o n i t o r e d o l d e r . < / l i >
< li > < strong > Staging Path < / s t r o n g > & m d a s h ; F o l d e r f o r t h e I m p o r t f e a t u r e ( f i l e s p l a c e d h e r e a p p e a r o n t h e I m p o r t p a g e ) / l i >
< li > < strong > Download Path < / s t r o n g > & m d a s h ; Th e f o l d e r w h e r e f i l e s a r e i n i t i a l l y d o w n l o a d e d . T h i s < s t r o n g > m u s t m a t c h < / s t r o n g > t h e f o l d e r y o u r d o w n l o a d s o u r c e ( s l s k d ) w r i t e s t o . I n D o c k e r , t h i s i s t h e c o n t a i n e r - s i d e m o u n t p o i n t ( 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 t h e h o s t p a t h . S o u l S y n c m o n i t o r s t h i s f o l d e r f o r c o m p l e t e d d o w n l o a d s t o b e g i n p o s t - p r o c e s s i n g . < / l i >
< li > < strong > Transfer Path < / s t r o n g > & m d a s h ; Th e f i n a l d e s t i n a t i o n f o r p r o c e s s e d m u s i c f i l e s . A f t e r t a g g i n g , r e n a m i n g , a n d o r g a n i z in g , f i l e s a r e m o v e d h e r e . T h i s < s t r o n g > m u s t < / s t r o n g > p o i n t t o y o u r m e d i a s e r v e r ' s m o n i t o r e d mu s i c fo l d e r ( t h e f o l d e r P l e x / J e l l y f i n / N a v i d r o m e w a t c h e s f o r n e w c o n t e n t ) . I n D o c k e r , u s e t h e c o n t a i n e r - s i d e p a t h ( e . g . , < c o d e > / a p p / T r a n s f e r < / c o d e > ) . < / l i >
< li > < strong > Staging Path < / s t r o n g > & m d a s h ; F o l d e r f o r t h e I m p o r t f e a t u r e ( f i l e s p l a c e d h e r e a p p e a r o n t h e I m p o r t p a g e ) . S e p a r a t e f r o m t h e d o w n l o a d / t r a n s f e r p i p e l i n e . </ l i >
< li > < strong > iTunes Country < / s t r o n g > & m d a s h ; S t o r e f r o n t r e g i o n f o r i T u n e s / A p p l e M u s i c l o o k u p s ( U S , G B , F R , J P , e t c . ) . C h a n g e s a p p l y i m m e d i a t e l y t o a l l s e a r c h e s w i t h o u t r e s t a r t i n g . I D - b a s e d l o o k u p s a u t o m a t i c a l l y t r y u p t o 1 0 r e g i o n a l s t o r e f r o n t s a s f a l l b a c k w h e n t h e p r i m a r y c o u n t r y r e t u r n s n o r e s u l t s . < / l i >
< li > < strong > Lossy Copy < / s t r o n g > & m d a s h ; W h e n e n a b l e d , c r e a t e s a l o w e r - b i t r a t e M P 3 c o p y o f e v e r y d o w n l o a d e d f i l e . C o n f i g u r e t h e o u t p u t b i t r a t e ( d e f a u l t 3 2 0 k b p s ) a n d o u t p u t f o l d e r . O p t i o n a l l y d e l e t e t h e o r i g i n a l l o s s l e s s f i l e a f t e r c r e a t i n g t h e l o s s y c o p y . U s e f u l f o r s y n c i n g t o m o b i l e d e v i c e s o r s t r e a m i n g s e r v e r s w i t h b a n d w i d t h c o n s t r a i n t s . < / l i >
< li > < strong > Content Filtering < / s t r o n g > & m d a s h ; T o g g l e e x p l i c i t c o n t e n t f i l t e r i n g t o c o n t r o l w h e t h e r e x p l i c i t t r a c k s a p p e a r i n s e a r c h r e s u l t s a n d d o w n l o a d s . < / l i >
< / u l >
< div class = "docs-callout warning" > < span class = "docs-callout-icon" > & # x26A0 ; & # xFE0F ; < / s p a n > < d i v > < s t r o n g > D o c k e r u s e r s : < / s t r o n g > A l w a y s u s e c o n t a i n e r - s i d e p a t h s i n t h e s e s e t t i n g s ( e . g . , < c o d e > / a p p / d o w n l o a d s < / c o d e > , < c o d e > / a p p / T r a n s f e r < / c o d e > ) . N e v e r u s e h o s t p a t h s l i k e < c o d e > / m n t / m u s i c < / c o d e > & m d a s h ; t h e c o n t a i n e r c a n ' t a c c e s s t h o s e . Y o u r d o c k e r - c o m p o s e < c o d e > v o l u m e s < / c o d e > s e c t i o n i s w h e r e h o s t p a t h s a r e m a p p e d t o c o n t a i n e r p a t h s . S e e < s t r o n g > G e t t i n g S t a r t e d & r a r r ; F o l d e r S e t u p < / s t r o n g > f o r a c o m p l e t e w a l k t h r o u g h . < / d i v > < / d i v >
< / d i v >
< div class = "docs-subsection" id = "set-processing" >
< h3 class = "docs-subsection-title" > Processing & Organization < / h 3 >
@ -1100,7 +1290,7 @@ function initializeDocsPage() {
} ) ;
// Search filter
const searchInput = document . getElementById ( 'docs-search ') ;
const searchInput = document . getElementById ( 'docs-search -input ') ;
if ( searchInput ) {
searchInput . addEventListener ( 'input' , ( ) => {
const q = searchInput . value . toLowerCase ( ) . trim ( ) ;
@ -1153,6 +1343,14 @@ function initializeDocsPage() {
}
} ) ;
// Default to first section if nothing scrolled past threshold yet
if ( ! activeSection && DOCS _SECTIONS . length ) {
activeSection = DOCS _SECTIONS [ 0 ] . id ;
if ( DOCS _SECTIONS [ 0 ] . children && DOCS _SECTIONS [ 0 ] . children . length ) {
activeChild = DOCS _SECTIONS [ 0 ] . children [ 0 ] . id ;
}
}
// Update nav highlighting
nav . querySelectorAll ( '.docs-nav-section-title' ) . forEach ( t => {
const isActive = t . dataset . target === activeSection ;
@ -1168,7 +1366,8 @@ function initializeDocsPage() {
} ) ;
}
// Auto-expand first section
// Reset scroll position and auto-expand first section
if ( docsContent ) docsContent . scrollTop = 0 ;
const firstTitle = nav . querySelector ( '.docs-nav-section-title' ) ;
if ( firstTitle ) {
firstTitle . classList . add ( 'expanded' , 'active' ) ;
Broque Thomas
2 months ago