feat(cli): add pls export/import subcommands for bulk playlist management (#5412)

* refactor: rename ImportFile to ImportFromFolder in playlists service

* feat: add ImportFile method with library/folder resolution

* feat: allow sync flag upgrade on re-import of non-synced playlists

* feat: add pls export subcommand with bulk and single export

Add `navidrome pls export` command that supports:
- Single playlist export to stdout (-p flag only)
- Single playlist export to directory (-p and -o flags)
- Bulk export of all playlists to a directory (-o flag only)
- Filtering by user (-u flag)
- Automatic filename sanitization and collision detection

Also extracts findPlaylist helper from runExporter for reuse.

* feat: add pls import subcommand with sync flag support

* fix: improve error message for export without output directory

* test: add tests for ImportFile sync flag and sync upgrade behavior

* refactor: streamline export and import logic by removing redundant comments and improving library path matching

Signed-off-by: Deluan <deluan@navidrome.org>

* feat: update ImportFile method to include sync flag for playlist imports

Signed-off-by: Deluan <deluan@navidrome.org>

* feat: implement fetchPlaylists function to streamline playlist retrieval

Signed-off-by: Deluan <deluan@navidrome.org>

* feat: replace inline filename sanitization with centralized utility function

Signed-off-by: Deluan <deluan@navidrome.org>

* feat: refactor playlist import logic to consolidate sync handling and improve method signatures

Signed-off-by: Deluan <deluan@navidrome.org>

* fix: address code review feedback on playlist import/export

- Fix duplicate playlist creation on non-sync re-import: only reconcile
  sync flag when the playlist was actually persisted (has an ID)
- Distinguish "not in any library" from real errors in resolveFolder
  using a sentinel error, so DB/folder errors propagate instead of
  falling back to ImportM3U
- Use bufio.Scanner in countM3UTrackLines instead of reading entire file

* feat: replace bufio.Scanner with UTF8Reader and LinesFrom utility for improved file reading

Signed-off-by: Deluan <deluan@navidrome.org>

* fix: record path for outside-library imports to prevent duplicates

Files outside all libraries now go through updatePlaylist with the
absolute path recorded, so re-importing the same file updates the
existing playlist instead of creating a duplicate.

* refactor: name guard condition in updatePlaylist for readability

Extracted the compound boolean expression into a named local variable
`alreadyImportedAndNotSynced` to make the intent of the early-return
guard clearer at a glance.

* add godocs

Signed-off-by: Deluan <deluan@navidrome.org>

---------

Signed-off-by: Deluan <deluan@navidrome.org>

cmd/pls.go

@@ -7,11 +7,19 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strconv"
+	"strings"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/ioutils"
+	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/navidrome/navidrome/utils/str"
 	"github.com/spf13/cobra"
 )
 
@@ -20,6 +28,7 @@ var (
 	outputFile   string
 	userID       string
 	outputFormat string
+	syncFlag     bool
 )
 
 type displayPlaylist struct {
@@ -41,6 +50,15 @@ func init() {
 	listCommand.Flags().StringVarP(&userID, "user", "u", "", "username or ID")
 	listCommand.Flags().StringVarP(&outputFormat, "format", "f", "csv", "output format [supported values: csv, json]")
 	plsCmd.AddCommand(listCommand)
+
+	exportCommand.Flags().StringVarP(&playlistID, "playlist", "p", "", "playlist name or ID")
+	exportCommand.Flags().StringVarP(&outputFile, "output", "o", "", "output directory")
+	exportCommand.Flags().StringVarP(&userID, "user", "u", "", "username or ID")
+	plsCmd.AddCommand(exportCommand)
+
+	importCommand.Flags().StringVarP(&userID, "user", "u", "", "owner username or ID (default: first admin)")
+	importCommand.Flags().BoolVar(&syncFlag, "sync", false, "mark imported playlists as synced")
+	plsCmd.AddCommand(importCommand)
 }
 
 var (
@@ -60,72 +78,165 @@ var (
 			runList(cmd.Context())
 		},
 	}
+
+	exportCommand = &cobra.Command{
+		Use:   "export",
+		Short: "Export playlists to M3U files",
+		Long:  "Export one or more Navidrome playlists to M3U files",
+		Run: func(cmd *cobra.Command, args []string) {
+			runExport(cmd.Context())
+		},
+	}
+
+	importCommand = &cobra.Command{
+		Use:   "import [files...]",
+		Short: "Import M3U playlists",
+		Long:  "Import one or more M3U files as Navidrome playlists",
+		Args:  cobra.MinimumNArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			runImport(cmd.Context(), args)
+		},
+	}
 )
 
-func runExporter(ctx context.Context) {
-	ds, ctx := getAdminContext(ctx)
-	playlist, err := ds.Playlist(ctx).GetWithTracks(playlistID, true, false)
+func fetchPlaylists(ctx context.Context, ds model.DataStore, sort string) model.Playlists {
+	options := model.QueryOptions{Sort: sort}
+	if userID != "" {
+		user, err := getUser(ctx, userID, ds)
+		if err != nil {
+			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
+		}
+		options.Filters = squirrel.Eq{"owner_id": user.ID}
+	}
+	pls, err := ds.Playlist(ctx).GetAll(options)
+	if err != nil {
+		log.Fatal(ctx, "Failed to retrieve playlists", err)
+	}
+	return pls
+}
+
+func findPlaylist(ctx context.Context, ds model.DataStore, nameOrID string) *model.Playlist {
+	playlist, err := ds.Playlist(ctx).GetWithTracks(nameOrID, true, false)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
-		log.Fatal("Error retrieving playlist", "name", playlistID, err)
+		log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 	}
 	if errors.Is(err, model.ErrNotFound) {
-		playlists, err := ds.Playlist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"playlist.name": playlistID}})
+		playlists, err := ds.Playlist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"playlist.name": nameOrID}})
 		if err != nil {
-			log.Fatal("Error retrieving playlist", "name", playlistID, err)
+			log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 		}
 		if len(playlists) > 0 {
 			playlist, err = ds.Playlist(ctx).GetWithTracks(playlists[0].ID, true, false)
 			if err != nil {
-				log.Fatal("Error retrieving playlist", "name", playlistID, err)
+				log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 			}
 		}
 	}
 	if playlist == nil {
-		log.Fatal("Playlist not found", "name", playlistID)
+		log.Fatal("Playlist not found", "name", nameOrID)
 	}
+	return playlist
+}
+
+func runExporter(ctx context.Context) {
+	ds, ctx := getAdminContext(ctx)
+	playlist := findPlaylist(ctx, ds, playlistID)
 	pls := playlist.ToM3U8()
 	if outputFile == "-" || outputFile == "" {
 		println(pls)
 		return
 	}
-
-	err = os.WriteFile(outputFile, []byte(pls), 0600)
+	err := os.WriteFile(outputFile, []byte(pls), 0600)
 	if err != nil {
 		log.Fatal("Error writing to the output file", "file", outputFile, err)
 	}
 }
 
+func runExport(ctx context.Context) {
+	ds, ctx := getAdminContext(ctx)
+
+	if playlistID != "" && outputFile == "" {
+		playlist := findPlaylist(ctx, ds, playlistID)
+		println(playlist.ToM3U8())
+		return
+	}
+
+	if outputFile == "" {
+		log.Fatal("Output directory (-o) is required for bulk export or when filtering by user")
+	}
+
+	info, err := os.Stat(outputFile)
+	if err != nil || !info.IsDir() {
+		log.Fatal("Output path must be an existing directory", "path", outputFile)
+	}
+
+	if playlistID != "" {
+		pls := findPlaylist(ctx, ds, playlistID)
+		filename := str.SanitizeFilename(pls.Name) + ".m3u"
+		path := filepath.Join(outputFile, filename)
+		err := os.WriteFile(path, []byte(pls.ToM3U8()), 0600)
+		if err != nil {
+			log.Fatal("Error writing playlist", "file", path, err)
+		}
+		fmt.Printf("Exported \"%s\" to %s\n", pls.Name, path)
+		return
+	}
+
+	allPls := fetchPlaylists(ctx, ds, "name")
+
+	nameCounts := make(map[string]int)
+	for _, pls := range allPls {
+		nameCounts[str.SanitizeFilename(pls.Name)]++
+	}
+
+	exported := 0
+	for _, pls := range allPls {
+		plsWithTracks, err := ds.Playlist(ctx).GetWithTracks(pls.ID, true, false)
+		if err != nil {
+			log.Error("Error loading playlist tracks", "playlist", pls.Name, err)
+			continue
+		}
+
+		sanitized := str.SanitizeFilename(pls.Name)
+		filename := sanitized + ".m3u"
+		if nameCounts[sanitized] > 1 {
+			shortID := pls.ID
+			if len(shortID) > 6 {
+				shortID = shortID[:6]
+			}
+			filename = sanitized + "_" + shortID + ".m3u"
+		}
+
+		path := filepath.Join(outputFile, filename)
+		err = os.WriteFile(path, []byte(plsWithTracks.ToM3U8()), 0600)
+		if err != nil {
+			log.Error("Error writing playlist", "file", path, err)
+			continue
+		}
+		fmt.Printf("Exported \"%s\" to %s\n", pls.Name, path)
+		exported++
+	}
+	fmt.Printf("\nExported %d playlists to %s\n", exported, outputFile)
+}
+
 func runList(ctx context.Context) {
 	if outputFormat != "csv" && outputFormat != "json" {
 		log.Fatal("Invalid output format. Must be one of csv, json", "format", outputFormat)
 	}
 
 	ds, ctx := getAdminContext(ctx)
-	options := model.QueryOptions{Sort: "owner_name"}
-
-	if userID != "" {
-		user, err := getUser(ctx, userID, ds)
-		if err != nil {
-			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
-		}
-		options.Filters = squirrel.Eq{"owner_id": user.ID}
-	}
-
-	playlists, err := ds.Playlist(ctx).GetAll(options)
-	if err != nil {
-		log.Fatal(ctx, "Failed to retrieve playlists", err)
-	}
+	allPls := fetchPlaylists(ctx, ds, "owner_name")
 
 	if outputFormat == "csv" {
 		w := csv.NewWriter(os.Stdout)
 		_ = w.Write([]string{"playlist id", "playlist name", "owner id", "owner name", "public"})
-		for _, playlist := range playlists {
+		for _, playlist := range allPls {
 			_ = w.Write([]string{playlist.ID, playlist.Name, playlist.OwnerID, playlist.OwnerName, strconv.FormatBool(playlist.Public)})
 		}
 		w.Flush()
 	} else {
-		display := make(displayPlaylists, len(playlists))
-		for idx, playlist := range playlists {
+		display := make(displayPlaylists, len(allPls))
+		for idx, playlist := range allPls {
 			display[idx].Id = playlist.ID
 			display[idx].Name = playlist.Name
 			display[idx].OwnerId = playlist.OwnerID
@@ -137,3 +248,62 @@ func runList(ctx context.Context) {
 		fmt.Printf("%s\n", j)
 	}
 }
+
+func runImport(ctx context.Context, files []string) {
+	ds, ctx := getAdminContext(ctx)
+
+	if userID != "" {
+		user, err := getUser(ctx, userID, ds)
+		if err != nil {
+			log.Fatal(ctx, "Error retrieving user", "username or id", userID)
+		}
+		ctx = request.WithUser(ctx, *user)
+	}
+
+	pls := playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+	for _, file := range files {
+		absPath, err := filepath.Abs(file)
+		if err != nil {
+			log.Error("Error resolving path", "file", file, err)
+			fmt.Fprintf(os.Stderr, "Error: could not resolve path %s: %v\n", file, err)
+			continue
+		}
+
+		totalLines := countM3UTrackLines(absPath)
+
+		imported, err := pls.ImportFile(ctx, absPath, syncFlag)
+		if err != nil {
+			log.Error("Error importing playlist", "file", absPath, err)
+			fmt.Fprintf(os.Stderr, "Error importing %s: %v\n", file, err)
+			continue
+		}
+
+		matched := len(imported.Tracks)
+		if totalLines > 0 {
+			notFound := totalLines - matched
+			fmt.Printf("Imported \"%s\" — %d/%d tracks matched (%d not found)\n", imported.Name, matched, totalLines, notFound)
+		} else {
+			fmt.Printf("Imported \"%s\" — %d tracks\n", imported.Name, matched)
+		}
+	}
+}
+
+func countM3UTrackLines(path string) int {
+	file, err := os.Open(path)
+	if err != nil {
+		return 0
+	}
+	defer file.Close()
+
+	count := 0
+	reader := ioutils.UTF8Reader(file)
+	for line := range slice.LinesFrom(reader) {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		count++
+	}
+	return count
+}

core/archiver.go

@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 type Archiver interface {
@@ -87,7 +88,7 @@ func (a *archiver) albumFilename(mf model.MediaFile, format string, isMultiDisc
 	if isMultiDisc {
 		file = fmt.Sprintf("Disc %02d/%s", mf.DiscNumber, file)
 	}
-	return fmt.Sprintf("%s/%s", sanitizeName(mf.Album), file)
+	return fmt.Sprintf("%s/%s", str.SanitizeFilename(mf.Album), file)
 }
 
 func (a *archiver) ZipShare(ctx context.Context, id string, out io.Writer) error {
@@ -126,7 +127,7 @@ func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format st
 
 	// Add M3U file if requested
 	if addM3U && len(zippedMfs) > 0 {
-		plsName := sanitizeName(name)
+		plsName := str.SanitizeFilename(name)
 		w, err := z.CreateHeader(&zip.FileHeader{
 			Name:     plsName + ".m3u",
 			Modified: mfs[0].UpdatedAt,
@@ -156,11 +157,7 @@ func (a *archiver) playlistFilename(mf model.MediaFile, format string, idx int)
 	if format != "" && format != "raw" {
 		ext = format
 	}
-	return fmt.Sprintf("%02d - %s - %s.%s", idx+1, sanitizeName(mf.Artist), sanitizeName(mf.Title), ext)
-}
-
-func sanitizeName(target string) string {
-	return strings.ReplaceAll(target, "/", "_")
+	return fmt.Sprintf("%02d - %s - %s.%s", idx+1, str.SanitizeFilename(mf.Artist), str.SanitizeFilename(mf.Title), ext)
 }
 
 func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.MediaFile, format string, bitrate int, filename string) error {

core/playlists/import.go

@@ -3,6 +3,7 @@ package playlists
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -17,14 +18,89 @@ import (
 	"golang.org/x/text/unicode/norm"
 )
 
-func (s *playlists) ImportFile(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
+func (s *playlists) ImportFile(ctx context.Context, absolutePath string, sync bool) (*model.Playlist, error) {
+	absPath, err := filepath.Abs(absolutePath)
+	if err != nil {
+		return nil, fmt.Errorf("resolving absolute path: %w", err)
+	}
+
+	dir := filepath.Dir(absPath)
+	filename := filepath.Base(absPath)
+
+	folder, err := s.resolveFolder(ctx, dir)
+	if err != nil && !errors.Is(err, errNotInLibrary) {
+		return nil, err
+	}
+	if err == nil {
+		pls, err := s.importFromFolder(ctx, folder, filename, sync)
+		if err != nil {
+			return nil, err
+		}
+		if pls.ID != "" && pls.Sync != sync {
+			pls.Sync = sync
+			if putErr := s.ds.Playlist(ctx).Put(pls); putErr != nil {
+				return nil, putErr
+			}
+		}
+		return pls, nil
+	}
+
+	log.Debug(ctx, "Playlist file is outside all libraries, using path-based import", "path", absPath)
+	pls, err := s.newSyncedPlaylist(dir, filename)
+	if err != nil {
+		return nil, fmt.Errorf("reading playlist file: %w", err)
+	}
+	pls.Sync = sync
+
+	file, err := os.Open(absPath)
+	if err != nil {
+		return nil, fmt.Errorf("opening playlist file: %w", err)
+	}
+	defer file.Close()
+
+	reader := ioutils.UTF8Reader(file)
+	if err := s.parseM3U(ctx, pls, nil, reader); err != nil {
+		return nil, err
+	}
+	if err := s.updatePlaylist(ctx, pls, sync); err != nil {
+		return nil, err
+	}
+	return pls, nil
+}
+
+var errNotInLibrary = fmt.Errorf("path not in any library")
+
+func (s *playlists) resolveFolder(ctx context.Context, dir string) (*model.Folder, error) {
+	libs, err := s.ds.Library(ctx).GetAll()
+	if err != nil {
+		return nil, err
+	}
+	matcher := newLibraryMatcher(libs)
+	lib, ok := matcher.findLibrary(dir)
+	if !ok {
+		return nil, fmt.Errorf("%w: %s", errNotInLibrary, dir)
+	}
+
+	folder, err := s.ds.Folder(ctx).GetByPath(lib, dir)
+	if err != nil {
+		return nil, fmt.Errorf("resolving folder for path %s: %w", dir, err)
+	}
+	folder.LibraryPath = lib.Path
+	return folder, nil
+}
+
+func (s *playlists) ImportFromFolder(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
+	return s.importFromFolder(ctx, folder, filename, false)
+}
+
+func (s *playlists) importFromFolder(ctx context.Context, folder *model.Folder, filename string, forceSync bool) (*model.Playlist, error) {
 	pls, err := s.parsePlaylist(ctx, filename, folder)
 	if err != nil {
 		log.Error(ctx, "Error parsing playlist", "path", filepath.Join(folder.AbsolutePath(), filename), err)
 		return nil, err
 	}
 	log.Debug(ctx, "Found playlist", "name", pls.Name, "lastUpdated", pls.UpdatedAt, "path", pls.Path, "numTracks", len(pls.Tracks))
-	err = s.updatePlaylist(ctx, pls)
+	err = s.updatePlaylist(ctx, pls, forceSync)
 	if err != nil {
 		log.Error(ctx, "Error updating playlist", "path", filepath.Join(folder.AbsolutePath(), filename), err)
 	}
@@ -74,27 +150,31 @@ func (s *playlists) parsePlaylist(ctx context.Context, playlistFile string, fold
 	return pls, err
 }
 
-func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist) error {
-	owner, _ := request.UserFrom(ctx)
-
-	// Try to find existing playlist by path. Since filesystem normalization differs across
-	// platforms (macOS uses NFD, Linux/Windows use NFC), we try both forms to match
-	// playlists that may have been imported on a different platform.
-	pls, err := s.ds.Playlist(ctx).FindByPath(newPls.Path)
+// findByPathNormalized looks up a playlist by path, trying both NFC and NFD Unicode
+// normalization forms to handle cross-platform filesystem differences.
+func (s *playlists) findByPathNormalized(ctx context.Context, path string) (*model.Playlist, error) {
+	pls, err := s.ds.Playlist(ctx).FindByPath(path)
 	if errors.Is(err, model.ErrNotFound) {
-		// Try alternate normalization form
-		altPath := norm.NFD.String(newPls.Path)
-		if altPath == newPls.Path {
-			altPath = norm.NFC.String(newPls.Path)
+		altPath := norm.NFD.String(path)
+		if altPath == path {
+			altPath = norm.NFC.String(path)
 		}
-		if altPath != newPls.Path {
+		if altPath != path {
 			pls, err = s.ds.Playlist(ctx).FindByPath(altPath)
 		}
 	}
+	return pls, err
+}
+
+func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist, forceSync bool) error {
+	owner, _ := request.UserFrom(ctx)
+
+	pls, err := s.findByPathNormalized(ctx, newPls.Path)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return err
 	}
-	if err == nil && !pls.Sync {
+	alreadyImportedAndNotSynced := err == nil && !pls.Sync && !forceSync
+	if alreadyImportedAndNotSynced {
 		log.Debug(ctx, "Playlist already imported and not synced", "playlist", pls.Name, "path", pls.Path)
 		return nil
 	}

core/playlists/import_test.go

@@ -39,7 +39,7 @@ var _ = Describe("Playlists - Import", func() {
 		ctx = request.WithUser(ctx, model.User{ID: "123"})
 	})
 
-	Describe("ImportFile", func() {
+	Describe("ImportFromFolder", func() {
 		var folder *model.Folder
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
@@ -59,7 +59,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		Describe("M3U", func() {
 			It("parses well-formed playlists", func() {
-				pls, err := ps.ImportFile(ctx, folder, "pls1.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "pls1.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Tracks).To(HaveLen(2))
@@ -69,19 +69,19 @@ var _ = Describe("Playlists - Import", func() {
 			})
 
 			It("parses playlists using LF ending", func() {
-				pls, err := ps.ImportFile(ctx, folder, "lf-ended.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "lf-ended.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 			})
 
 			It("parses playlists using CR ending (old Mac format)", func() {
-				pls, err := ps.ImportFile(ctx, folder, "cr-ended.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "cr-ended.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 			})
 
 			It("parses playlists with UTF-8 BOM marker", func() {
-				pls, err := ps.ImportFile(ctx, folder, "bom-test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "bom-test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Name).To(Equal("Test Playlist"))
@@ -90,7 +90,7 @@ var _ = Describe("Playlists - Import", func() {
 			})
 
 			It("parses UTF-16 LE encoded playlists with BOM and converts to UTF-8", func() {
-				pls, err := ps.ImportFile(ctx, folder, "bom-test-utf16.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "bom-test-utf16.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.OwnerID).To(Equal("123"))
 				Expect(pls.Name).To(Equal("UTF-16 Test Playlist"))
@@ -101,7 +101,7 @@ var _ = Describe("Playlists - Import", func() {
 			It("parses #EXTALBUMARTURL with HTTP URL", func() {
 				conf.Server.EnableM3UExternalAlbumArt = true
 
-				pls, err := ps.ImportFile(ctx, folder, "pls-with-art-url.m3u")
+				pls, err := ps.ImportFromFolder(ctx, folder, "pls-with-art-url.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal("https://example.com/cover.jpg"))
 				Expect(pls.Tracks).To(HaveLen(2))
@@ -121,7 +121,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
@@ -139,7 +139,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(filepath.Join(tmpDir, "cover.jpg")))
 			})
@@ -158,7 +158,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
@@ -177,7 +177,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(Equal(imgPath))
 			})
@@ -195,7 +195,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -212,7 +212,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -229,7 +229,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -247,7 +247,7 @@ var _ = Describe("Playlists - Import", func() {
 				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -275,12 +275,38 @@ var _ = Describe("Playlists - Import", func() {
 				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.UploadedImage).To(Equal("existing-id.jpg"))
 				Expect(pls.ExternalImageURL).To(Equal("https://example.com/new-cover.jpg"))
 			})
 
+			It("skips non-synced playlist on re-import (respects user's choice)", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
+				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+				plsFile := filepath.Join(tmpDir, "test.m3u")
+				Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+				existingPls := &model.Playlist{
+					ID:      "existing-id",
+					Name:    "Existing Playlist",
+					Path:    plsFile,
+					Sync:    false,
+					OwnerID: "123",
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
+				Expect(err).ToNot(HaveOccurred())
+				// updatePlaylist skips the non-synced playlist, so the returned
+				// playlist has no ID (was never persisted/updated).
+				Expect(pls.ID).To(BeEmpty())
+			})
+
 			It("clears ExternalImageURL on re-scan when directive is removed", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
@@ -301,7 +327,7 @@ var _ = Describe("Playlists - Import", func() {
 				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
@@ -309,7 +335,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		Describe("NSP", func() {
 			It("parses well-formed playlists", func() {
-				pls, err := ps.ImportFile(ctx, folder, "recently_played.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "recently_played.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last).To(Equal(pls))
 				Expect(pls.OwnerID).To(Equal("123"))
@@ -322,17 +348,17 @@ var _ = Describe("Playlists - Import", func() {
 			})
 			It("returns an error if the playlist is not well-formed", func() {
 				tests.SkipOnWindows("line-ending differences affect JSON error offset")
-				_, err := ps.ImportFile(ctx, folder, "invalid_json.nsp")
+				_, err := ps.ImportFromFolder(ctx, folder, "invalid_json.nsp")
 				Expect(err.Error()).To(ContainSubstring("line 19, column 1: invalid character '\\n'"))
 			})
 			It("parses NSP with public: true and creates public playlist", func() {
-				pls, err := ps.ImportFile(ctx, folder, "public_playlist.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "public_playlist.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Public Playlist"))
 				Expect(pls.Public).To(BeTrue())
 			})
 			It("parses NSP with public: false and creates private playlist", func() {
-				pls, err := ps.ImportFile(ctx, folder, "private_playlist.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "private_playlist.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Private Playlist"))
 				Expect(pls.Public).To(BeFalse())
@@ -340,7 +366,7 @@ var _ = Describe("Playlists - Import", func() {
 			It("uses server default when public field is absent", func() {
 				conf.Server.DefaultPlaylistPublicVisibility = true
 
-				pls, err := ps.ImportFile(ctx, folder, "recently_played.nsp")
+				pls, err := ps.ImportFromFolder(ctx, folder, "recently_played.nsp")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Name).To(Equal("Recently Played"))
 				Expect(pls.Public).To(BeTrue()) // Should be true since server default is true
@@ -386,7 +412,7 @@ var _ = Describe("Playlists - Import", func() {
 					Path:        "",
 					Name:        "",
 				}
-				pls, err := ps.ImportFile(ctx, plsFolder, filesystemName+".m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, filesystemName+".m3u")
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should update existing playlist, not create new one
@@ -441,7 +467,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("abc.mp3")) // From songsDir library
@@ -462,7 +488,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				// Should only find abc.mp3, not outside.mp3
 				Expect(pls.Tracks).To(HaveLen(1))
@@ -499,7 +525,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "subfolder", // The folder name
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("abc.mp3")) // From songsDir library
@@ -542,7 +568,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(2))
 				Expect(pls.Tracks[0].Path).To(Equal("rock.mp3")) // From music library
@@ -593,7 +619,7 @@ var _ = Describe("Playlists - Import", func() {
 					Name:        "",
 				}
 
-				pls, err := ps.ImportFile(ctx, plsFolder, "test.m3u")
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should have BOTH tracks, not just one
@@ -616,6 +642,126 @@ var _ = Describe("Playlists - Import", func() {
 		})
 	})
 
+	Describe("ImportFile", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3", "test.ogg"}}
+		})
+
+		It("resolves file inside a library and imports it", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID:          "1",
+					LibraryID:   1,
+					LibraryPath: tmpDir,
+					Path:        "",
+					Name:        "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsContent := "#PLAYLIST:My Playlist\ntest.mp3\ntest.ogg\n"
+			plsFile := filepath.Join(tmpDir, "my-playlist.m3u")
+			Expect(os.WriteFile(plsFile, []byte(plsContent), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Name).To(Equal("My Playlist"))
+			Expect(pls.Tracks).To(HaveLen(2))
+			Expect(pls.Path).To(Equal(plsFile))
+			Expect(pls.Sync).To(BeTrue())
+		})
+
+		It("records path for files outside all libraries", func() {
+			tmpDir := GinkgoT().TempDir()
+			libDir := filepath.Join(tmpDir, "music")
+			Expect(os.Mkdir(libDir, 0755)).To(Succeed())
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: libDir}})
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsContent := "#PLAYLIST:External Playlist\n" + libDir + "/test.mp3\n"
+			plsFile := filepath.Join(tmpDir, "external.m3u")
+			Expect(os.WriteFile(plsFile, []byte(plsContent), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Name).To(Equal("External Playlist"))
+			Expect(pls.Path).To(Equal(plsFile))
+			Expect(pls.Sync).To(BeFalse())
+		})
+
+		It("imports with Sync=false", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Sync).To(BeFalse())
+		})
+
+		It("imports with Sync=true", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.Sync).To(BeTrue())
+		})
+
+		It("upgrades non-synced playlist to synced on re-import with sync=true", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+
+			plsFile := filepath.Join(tmpDir, "test.m3u")
+			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+
+			existingPls := &model.Playlist{
+				ID: "existing-id", Name: "Existing", Path: plsFile,
+				Sync: false, OwnerID: "123",
+			}
+			mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+			pls, err := ps.ImportFile(ctx, plsFile, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.ID).To(Equal("existing-id"))
+			Expect(pls.Sync).To(BeTrue())
+		})
+	})
+
 	Describe("ImportM3U", func() {
 		var repo *mockedMediaFileFromListRepo
 		BeforeEach(func() {
@@ -925,3 +1071,15 @@ func (r *mockedMediaFileFromListRepo) FindByPaths(paths []string) (model.MediaFi
 	}
 	return mfs, nil
 }
+
+type mockFolderRepoForImport struct {
+	model.FolderRepository
+	folder *model.Folder
+}
+
+func (m *mockFolderRepoForImport) GetByPath(_ model.Library, _ string) (*model.Folder, error) {
+	if m.folder != nil {
+		return m.folder, nil
+	}
+	return nil, model.ErrNotFound
+}

core/playlists/parse_m3u.go

@@ -163,17 +163,26 @@ type libraryMatcher struct {
 // findLibraryForPath finds which library contains the given absolute path.
 // Returns library ID and path, or 0 and empty string if not found.
 func (lm *libraryMatcher) findLibraryForPath(absolutePath string) (int, string) {
+	lib, ok := lm.findLibrary(absolutePath)
+	if !ok {
+		return 0, ""
+	}
+	return lib.ID, filepath.Clean(lib.Path)
+}
+
+// findLibrary checks if the absolute path is under any of the library paths.
+func (lm *libraryMatcher) findLibrary(absolutePath string) (model.Library, bool) {
 	// Check sorted libraries (longest path first) to find the best match
 	for i, cleanLibPath := range lm.cleanedPaths {
 		// Check if absolutePath is under this library path
 		if strings.HasPrefix(absolutePath, cleanLibPath) {
 			// Ensure it's a proper path boundary (not just a prefix)
 			if len(absolutePath) == len(cleanLibPath) || absolutePath[len(cleanLibPath)] == filepath.Separator {
-				return lm.libraries[i].ID, cleanLibPath
+				return lm.libraries[i], true
 			}
 		}
 	}
-	return 0, ""
+	return model.Library{}, false
 }
 
 // newLibraryMatcher creates a libraryMatcher with libraries sorted by path length (longest first).

core/playlists/playlists.go

@@ -42,10 +42,11 @@ type Playlists interface {
 	RemoveImage(ctx context.Context, playlistID string) error
 
 	// Import
-	ImportFile(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error)
+	ImportFile(ctx context.Context, absolutePath string, sync bool) (*model.Playlist, error)
+	ImportFromFolder(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error)
 	ImportM3U(ctx context.Context, reader io.Reader) (*model.Playlist, error)
 
-	// REST adapters (follows Share/Library pattern)
+	// REST adapters
 	NewRepository(ctx context.Context) rest.Repository
 	TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository
 }

scanner/phase_4_playlists.go

@@ -100,7 +100,7 @@ func (p *phasePlaylists) processPlaylistsInFolder(folder *model.Folder) (*model.
 			continue
 		}
 		// BFR: Check if playlist needs to be refreshed (timestamp, sync flag, etc)
-		pls, err := p.pls.ImportFile(p.ctx, folder, f.Name())
+		pls, err := p.pls.ImportFromFolder(p.ctx, folder, f.Name())
 		if err != nil {
 			continue
 		}

scanner/phase_4_playlists_test.go

@@ -97,9 +97,9 @@ var _ = Describe("phasePlaylists", func() {
 			_ = os.WriteFile(file1, []byte{}, 0600)
 			_ = os.WriteFile(file2, []byte{}, 0600)
 
-			pls.On("ImportFile", mock.Anything, folder, "playlist1.m3u").
+			pls.On("ImportFromFolder", mock.Anything, folder, "playlist1.m3u").
 				Return(&model.Playlist{}, nil)
-			pls.On("ImportFile", mock.Anything, folder, "playlist2.m3u").
+			pls.On("ImportFromFolder", mock.Anything, folder, "playlist2.m3u").
 				Return(&model.Playlist{}, nil)
 
 			_, err := phase.processPlaylistsInFolder(folder)
@@ -134,7 +134,7 @@ type mockPlaylists struct {
 	playlists.Playlists
 }
 
-func (p *mockPlaylists) ImportFile(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
+func (p *mockPlaylists) ImportFromFolder(ctx context.Context, folder *model.Folder, filename string) (*model.Playlist, error) {
 	args := p.Called(ctx, folder, filename)
 	return args.Get(0).(*model.Playlist), args.Error(1)
 }

utils/str/sanitize_strings.go

@@ -52,6 +52,22 @@ func SanitizeHTML(text string) string {
 	return policy.Sanitize(html.UnescapeString(text))
 }
 
+var filenameReplacer = strings.NewReplacer(
+	"/", "_",
+	"\\", "_",
+	":", "_",
+	"*", "_",
+	"?", "_",
+	"\"", "_",
+	"<", "_",
+	">", "_",
+	"|", "_",
+)
+
+func SanitizeFilename(name string) string {
+	return filenameReplacer.Replace(name)
+}
+
 func SanitizeFieldForSorting(originalValue string) string {
 	v := strings.TrimSpace(sanitize.Accents(originalValue))
 	return Clear(strings.ToLower(v))