Preserve media metadata across STRM path renames

.dockerignore

@@ -14,6 +14,7 @@ verify-cache/
 verify-media/
 verify-downloads/
 .codex-*
+.codex/
 .tmp/
 .tmp_*
 .tmp-deploy-*

.gitignore

@@ -66,6 +66,7 @@ config.yaml
 .tmp-live-backups/
 .tmp-*
 .codex-*
+.codex/
 downloads/
 media/
 *.pid

internal/handler/routes_authenticated_core.go

@@ -54,6 +54,7 @@ func registerAuthedMediaRoutes(authed *gin.RouterGroup, svc *service.Container)
 	authed.DELETE("/media/:id", middleware.AdminRequired(), deleteMediaHandler(svc))
 	authed.GET("/media/:id/subtitles", listSubtitlesHandler(svc))
 	authed.GET("/subtitles/:id", serveSubtitleHandler(svc))
+	authed.GET("/subtitles/:id/ass", serveASSSubtitleHandler(svc))
 	authed.POST("/media/:id/nfo", middleware.AdminRequired(), exportNFOHandler(svc))
 	authed.POST("/libraries/:id/nfo", middleware.AdminRequired(), exportLibraryNFOHandler(svc))
 }

internal/handler/subtitles.go

@@ -34,6 +34,22 @@ func listSubtitlesHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+func serveASSSubtitleHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		path := c.Query("path")
+		if path == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "missing path"})
+			return
+		}
+		c.Header("Content-Type", "text/plain; charset=utf-8")
+		c.Header("Cache-Control", "no-cache, no-store, must-revalidate")
+		if err := svc.Subtitle.ServeASS(c.Request.Context(), c.Param("id"), path, c.Writer); err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+	}
+}
+
 func serveSubtitleHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		path := c.Query("path")

internal/repository/media_repository_upsert.go

@@ -3,6 +3,7 @@ package repository
 import (
 	"context"
 	"errors"
+	"path/filepath"
 	"strings"
 
 	"gorm.io/gorm"
@@ -10,6 +11,18 @@ import (
 	"github.com/truewhile/MeBox/internal/model"
 )
 
+// MediaUpsertItem carries a media row and optional sibling paths from an
+// earlier keep_ext naming mode. An alias is only used when the exact new path
+// does not exist in the database; in that case the existing row is migrated to
+// the new path so scraped metadata survives renames such as:
+//
+//	foo.strm -> foo.mkv.strm
+//	foo.mkv.strm -> foo.strm
+type MediaUpsertItem struct {
+	Media      *model.Media
+	AliasPaths []string
+}
+
 // Upsert inserts or updates a media row keyed by Path (unique index).
 //
 // 重要：当一条行已经存在时，scanner 重扫只应该刷新文件级元数据
@@ -22,20 +35,14 @@ import (
 //     显式写入）。这两个问题都让 EnrichLibrary(WHERE scrape_status='pending')
 //     永远捞不到数据。
 func (r *MediaRepository) Upsert(ctx context.Context, m *model.Media) error {
-	var indexIDs []string
-	err := withSQLiteBusyRetry(ctx, func() error {
-		id, uerr := r.upsertWithDB(ctx, r.db, m)
-		if uerr != nil {
-			return uerr
-		}
-		indexIDs = append(indexIDs[:0], id)
-		return nil
-	})
-	if err != nil {
-		return err
-	}
-	r.indexByIDBestEffort(ctx, indexIDs)
-	return nil
+	return r.UpsertWithAliases(ctx, m, nil)
+}
+
+// UpsertWithAliases is Upsert with explicit, filesystem-verified STRM sibling
+// aliases. It preserves the old row's ID, CreatedAt and scraped metadata while
+// moving it to the current path.
+func (r *MediaRepository) UpsertWithAliases(ctx context.Context, m *model.Media, aliasPaths []string) error {
+	return r.UpsertBatchWithAliases(ctx, []MediaUpsertItem{{Media: m, AliasPaths: aliasPaths}})
 }
 
 // UpsertBatch 在单个事务里逐条执行 Upsert：扫描一批只提交（fsync）一次，
@@ -46,6 +53,17 @@ func (r *MediaRepository) Upsert(ctx context.Context, m *model.Media) error {
 // 事务内会把 SQLite 写锁挂起在网络 IO 上，且批内用非事务连接回读只能
 // 拿到提交前的旧版本数据，把陈旧内容写进索引。
 func (r *MediaRepository) UpsertBatch(ctx context.Context, items []*model.Media) error {
+	mapped := make([]MediaUpsertItem, 0, len(items))
+	for _, item := range items {
+		if item != nil {
+			mapped = append(mapped, MediaUpsertItem{Media: item})
+		}
+	}
+	return r.UpsertBatchWithAliases(ctx, mapped)
+}
+
+// UpsertBatchWithAliases runs alias-aware upserts in one transaction.
+func (r *MediaRepository) UpsertBatchWithAliases(ctx context.Context, items []MediaUpsertItem) error {
 	if len(items) == 0 {
 		return nil
 	}
@@ -53,11 +71,11 @@ func (r *MediaRepository) UpsertBatch(ctx context.Context, items []*model.Media)
 	err := withSQLiteBusyRetry(ctx, func() error {
 		indexIDs = indexIDs[:0]
 		return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-			for _, m := range items {
-				if m == nil {
+			for _, item := range items {
+				if item.Media == nil {
 					continue
 				}
-				id, err := r.upsertWithDB(ctx, tx, m)
+				id, err := r.upsertWithDB(ctx, tx, item.Media, item.AliasPaths)
 				if err != nil {
 					return err
 				}
@@ -87,9 +105,9 @@ func (r *MediaRepository) indexByIDBestEffort(ctx context.Context, ids []string)
 	}
 }
 
-// upsertWithDB 落库（新建或更新），返回需要重建索引的媒体 ID（无则空串）。
-func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *model.Media) (string, error) {
-	existing, created, err := r.findOrCreateMediaByPath(ctx, db, m)
+// upsertWithDB 落库（新建、更新或从旧路径迁移），返回需要重建索引的媒体 ID。
+func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *model.Media, aliasPaths []string) (string, error) {
+	existing, created, adopted, err := r.findOrCreateMediaByPath(ctx, db, m, aliasPaths)
 	if err != nil {
 		return "", err
 	}
@@ -98,6 +116,12 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 	}
 
 	updates := mediaUpsertUpdates(existing, *m)
+	if adopted {
+		updates["path"] = m.Path
+		if existing.DeletedAt.Valid {
+			updates["deleted_at"] = nil
+		}
+	}
 	if len(updates) == 0 {
 		*m = existing
 		return "", nil
@@ -107,31 +131,67 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 		return "", err
 	}
 	// 回写 ID / 不可变字段，让 caller 拿到完整的现有行。
+	if adopted {
+		existing.Path = m.Path
+		existing.DeletedAt = gorm.DeletedAt{}
+	}
 	*m = existing
 	return existing.ID, nil
 }
 
-func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.DB, m *model.Media) (model.Media, bool, error) {
+func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.DB, m *model.Media, aliasPaths []string) (model.Media, bool, bool, error) {
 	var existing model.Media
 	err := db.WithContext(ctx).Unscoped().Where("path = ?", m.Path).First(&existing).Error
 	if errors.Is(err, gorm.ErrRecordNotFound) {
+		if alias, aliasErr := r.findMediaByAlias(ctx, db, m.Path, aliasPaths); aliasErr == nil {
+			return alias, false, true, nil
+		} else if !errors.Is(aliasErr, gorm.ErrRecordNotFound) {
+			return model.Media{}, false, false, aliasErr
+		}
 		// 新行：保证 scrape_status 走 GORM default:pending（即留空让数据库填）。
 		if m.ScrapeStatus == "" {
 			m.ScrapeStatus = "pending"
 		}
 		if createErr := db.WithContext(ctx).Create(m).Error; createErr == nil {
-			return *m, true, nil
+			return *m, true, false, nil
 		} else if retryErr := db.WithContext(ctx).Unscoped().Where("path = ?", m.Path).First(&existing).Error; retryErr != nil {
-			return model.Media{}, false, createErr
+			return model.Media{}, false, false, createErr
 		} else {
 			// 并发插入竞态：重查已命中既有行，直接走更新分支。
-			return existing, false, nil
+			return existing, false, false, nil
 		}
 	}
 	if err != nil {
-		return model.Media{}, false, err
+		return model.Media{}, false, false, err
 	}
-	return existing, false, nil
+	return existing, false, false, nil
+}
+
+func (r *MediaRepository) findMediaByAlias(ctx context.Context, db *gorm.DB, currentPath string, aliasPaths []string) (model.Media, error) {
+	aliases := make([]string, 0, len(aliasPaths))
+	seen := make(map[string]struct{}, len(aliasPaths))
+	for _, alias := range aliasPaths {
+		alias = filepath.Clean(strings.TrimSpace(alias))
+		if alias == "" || alias == "." || alias == filepath.Clean(currentPath) {
+			continue
+		}
+		if _, ok := seen[alias]; ok {
+			continue
+		}
+		seen[alias] = struct{}{}
+		aliases = append(aliases, alias)
+	}
+	if len(aliases) == 0 {
+		return model.Media{}, gorm.ErrRecordNotFound
+	}
+	var existing model.Media
+	err := db.WithContext(ctx).Unscoped().
+		Where("path IN ?", aliases).
+		Order("CASE WHEN scrape_status = 'matched' THEN 0 ELSE 1 END ASC, " +
+			"CASE WHEN COALESCE(poster_url, '') <> '' OR COALESCE(overview, '') <> '' THEN 0 ELSE 1 END ASC, " +
+			"CASE WHEN deleted_at IS NULL THEN 0 ELSE 1 END ASC, updated_at DESC, created_at DESC").
+		First(&existing).Error
+	return existing, err
 }
 
 func mediaUpsertUpdates(existing, incoming model.Media) map[string]any {

internal/service/local_metadata_artwork.go

@@ -158,7 +158,7 @@ func firstExistingImage(dir string, names ...string) string {
 		return ""
 	}
 	for _, name := range names {
-		for _, ext := range []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn"} {
+		for _, ext := range []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn", ".img"} {
 			path := filepath.Join(dir, name+ext)
 			if fileExists(path) {
 				return filepath.Clean(path)
@@ -221,7 +221,7 @@ func firstExistingPosterImage(dir string, names ...string) string {
 		if isRejectedPosterName(name) {
 			continue
 		}
-		for _, ext := range []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn"} {
+		for _, ext := range []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn", ".img"} {
 			path := filepath.Join(dir, name+ext)
 			if fileExists(path) && likelyPosterImage(path) {
 				return filepath.Clean(path)
@@ -240,7 +240,7 @@ func firstAdultLooseImage(dir, kind string) string {
 	fallback := []string{}
 	for _, path := range matches {
 		ext := strings.ToLower(filepath.Ext(path))
-		if ext != ".jpg" && ext != ".jpeg" && ext != ".png" && ext != ".webp" && ext != ".gif" && ext != ".bmp" && ext != ".tbn" {
+		if ext != ".jpg" && ext != ".jpeg" && ext != ".png" && ext != ".webp" && ext != ".gif" && ext != ".bmp" && ext != ".tbn" && ext != ".img" {
 			continue
 		}
 		name := strings.ToLower(strings.TrimSuffix(filepath.Base(path), ext))

internal/service/local_metadata_test.go

@@ -417,3 +417,22 @@ func TestReadLocalMetadataArtworkFallbackOnGarbageShowNFO(t *testing.T) {
 		t.Fatalf("expected episode artwork fallback, got %+v", got)
 	}
 }
+
+func TestReadLocalMetadataFindsLegacyImgPoster(t *testing.T) {
+	root := t.TempDir()
+	mediaPath := filepath.Join(root, "Jigokuraku.S01E14.mkv.strm")
+	poster := filepath.Join(root, "Jigokuraku.S01E14-poster.img")
+	if err := os.WriteFile(mediaPath, []byte("https://example.test/video"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(poster, testJPEG, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := ReadLocalMetadata(mediaPath, root, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil || got.PosterURL != poster {
+		t.Fatalf("PosterURL = %q, want legacy .img poster %q", got.PosterURL, poster)
+	}
+}

internal/service/media_path_alias.go

@@ -0,0 +1,101 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// strmPathAliases returns sibling STRM names that can represent the same media
+// item when keep_ext is toggled on or off.
+//
+// Both directions are supported:
+//
+//	foo.strm      <-> foo.mkv.strm
+//	foo.strm      <-> foo.mp4.strm
+//
+// The caller must still verify that the aliases are no longer present on disk.
+// keep_ext intentionally allows foo.mkv.strm and foo.mp4.strm to coexist as
+// two real versions, so an existing sibling must never be absorbed.
+func strmPathAliases(path string) []string {
+	clean := filepath.Clean(strings.TrimSpace(path))
+	if clean == "" || clean == "." || !strings.EqualFold(filepath.Ext(clean), ".strm") {
+		return nil
+	}
+	base := mediaSidecarBase(clean)
+	if base == "" {
+		return nil
+	}
+	name := filepath.Base(clean)
+	stem := strings.TrimSuffix(name, filepath.Ext(name))
+	lastExt := strings.ToLower(filepath.Ext(stem))
+	_, hasVideoExt := videoExtensions[lastExt]
+	hasVideoExt = hasVideoExt && !strings.EqualFold(lastExt, ".strm")
+
+	dir := filepath.Dir(clean)
+	out := make([]string, 0, len(videoExtensions)+1)
+	seen := make(map[string]struct{}, len(videoExtensions)+1)
+	add := func(candidate string) {
+		candidate = filepath.Clean(candidate)
+		if candidate == "" || candidate == "." || samePath(candidate, clean) {
+			return
+		}
+		key := strings.ToLower(candidate)
+		if _, ok := seen[key]; ok {
+			return
+		}
+		seen[key] = struct{}{}
+		out = append(out, candidate)
+	}
+	if hasVideoExt {
+		// Current keep_ext shape: the only legacy shape is the stripped name.
+		add(filepath.Join(dir, base+".strm"))
+		return out
+	}
+	// Stripped shape: an old keep_ext file may use any configured video ext.
+	exts := make([]string, 0, len(videoExtensions))
+	for ext := range videoExtensions {
+		if strings.EqualFold(ext, ".strm") {
+			continue
+		}
+		exts = append(exts, strings.ToLower(ext))
+	}
+	sort.Strings(exts)
+	for _, ext := range exts {
+		add(filepath.Join(dir, base+ext+".strm"))
+		if upper := strings.ToUpper(ext); upper != ext {
+			add(filepath.Join(dir, base+upper+".strm"))
+		}
+	}
+	return out
+}
+
+// missingSTRMPathAliases keeps only aliases which no longer exist on disk.
+// This is the key protection for keep_ext=true multi-version libraries: an
+// existing foo.mp4.strm is a real second version, not a rename tombstone.
+func missingSTRMPathAliases(path string) []string {
+	aliases := strmPathAliases(path)
+	if len(aliases) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(aliases))
+	for _, alias := range aliases {
+		if _, err := os.Lstat(alias); err == nil {
+			continue
+		} else if !os.IsNotExist(err) {
+			continue
+		}
+		out = append(out, alias)
+	}
+	return out
+}
+
+func liveSTRMPathAlias(path string) bool {
+	for _, alias := range strmPathAliases(path) {
+		if info, err := os.Stat(alias); err == nil && !info.IsDir() {
+			return true
+		}
+	}
+	return false
+}

internal/service/media_series.go

@@ -301,16 +301,8 @@ func groupMediaSeriesCards(items []model.Media) []SeriesCard {
 			if betterSeriesLinkMedia(item, card.LinkMedia) {
 				card.LinkMedia = item
 			}
-			currentArtwork := seriesArtworkScore(item)
-			representativeArtwork := seriesArtworkScore(card.Rep)
-			if currentArtwork > representativeArtwork {
+			if betterSeriesRepresentative(item, card.Rep) {
 				card.Rep = item
-			} else if currentArtwork == representativeArtwork {
-				cur := item.SeasonNum*10000 + item.EpisodeNum
-				rep := card.Rep.SeasonNum*10000 + card.Rep.EpisodeNum
-				if cur > 0 && (rep == 0 || cur < rep) {
-					card.Rep = item
-				}
 			}
 			continue
 		}
@@ -335,6 +327,27 @@ func groupMediaSeriesCards(items []model.Media) []SeriesCard {
 	return cards
 }
 
+func betterSeriesRepresentative(candidate, current model.Media) bool {
+	// A theatrical feature can have local poster.jpg/background.jpg files and
+	// therefore a higher artwork score than its TV episodes. Keep the TV row as
+	// the visible identity of a mixed series card so a movie cannot hijack the
+	// series title, overview, and artwork.
+	candidateTheatrical := mediaLooksLikeTheatricalFeature(&candidate)
+	currentTheatrical := mediaLooksLikeTheatricalFeature(&current)
+	if candidateTheatrical != currentTheatrical {
+		return !candidateTheatrical
+	}
+
+	currentArtwork := seriesArtworkScore(candidate)
+	representativeArtwork := seriesArtworkScore(current)
+	if currentArtwork != representativeArtwork {
+		return currentArtwork > representativeArtwork
+	}
+	cur := candidate.SeasonNum*10000 + candidate.EpisodeNum
+	rep := current.SeasonNum*10000 + current.EpisodeNum
+	return cur > 0 && (rep == 0 || cur < rep)
+}
+
 func seriesMediaTime(media model.Media) time.Time {
 	if releaseDate := strings.TrimSpace(media.ReleaseDate); releaseDate != "" {
 		if parsed, err := time.Parse("2006-01-02", releaseDate); err == nil {

internal/service/media_series_resolver.go

@@ -67,17 +67,20 @@ func newMediaSeriesKeyResolver(items []model.Media) mediaSeriesKeyResolver {
 
 func (r mediaSeriesKeyResolver) key(media model.Media) string {
 	if mediaLooksEpisodicForGrouping(media) {
-		if key := repeatedSeriesTitleKey(media); key != "" && r.titleCounts[key] > 1 {
-			return compactSeriesKey(key)
-		}
 		if pathKey := mediaSeriesRawKey(media); strings.HasPrefix(pathKey, "library-path") {
 			if titleKey := r.pathTitles[pathKey]; titleKey != "" {
 				return compactSeriesKey(titleKey)
 			}
+			// A series directory is the strongest identity for mixed rows:
+			// main episodes and specials (CM/NCOP/PV/OVA) may be scraped to
+			// slightly different titles, but they still belong to one show.
 			if r.pathCounts[pathKey] > 1 {
 				return compactSeriesKey(pathKey)
 			}
 		}
+		if key := repeatedSeriesTitleKey(media); key != "" && r.titleCounts[key] > 1 {
+			return compactSeriesKey(key)
+		}
 		if key := repeatedSeriesExternalKey(media); key != "" && r.externalCounts[key] > 1 {
 			return compactSeriesKey(key)
 		}

internal/service/media_series_test.go

@@ -47,14 +47,14 @@ func TestListRecentSeriesCardsCountsAllEpisodesInSeries(t *testing.T) {
 	if len(cards) != 1 {
 		t.Fatalf("recent cards = %#v, want one series card", cards)
 	}
-		if cards[0].Count != 40 {
-			t.Fatalf("recent series count = %d, want full 40 episodes", cards[0].Count)
-		}
-		expectedLastAdded := now.Add(40 * time.Minute)
-		if cards[0].LastAddedAt == nil || !cards[0].LastAddedAt.Equal(expectedLastAdded) {
-			t.Fatalf("recent series LastAddedAt = %v, want %v", cards[0].LastAddedAt, expectedLastAdded)
-		}
+	if cards[0].Count != 40 {
+		t.Fatalf("recent series count = %d, want full 40 episodes", cards[0].Count)
 	}
+	expectedLastAdded := now.Add(40 * time.Minute)
+	if cards[0].LastAddedAt == nil || !cards[0].LastAddedAt.Equal(expectedLastAdded) {
+		t.Fatalf("recent series LastAddedAt = %v, want %v", cards[0].LastAddedAt, expectedLastAdded)
+	}
+}
 
 func TestMediaSeriesKeyCollapsesNestedSpecialFolders(t *testing.T) {
 	main := model.Media{
@@ -377,6 +377,51 @@ func TestGroupMediaSeriesCardsMergesPollutedEpisodeFoldersBySharedShowID(t *test
 	}
 }
 
+func TestGroupMediaSeriesCardsKeepsMixedTitlesInSameEpisodicDirectoryTogether(t *testing.T) {
+	items := []model.Media{
+		{
+			Base:         model.Base{ID: "main-1"},
+			LibraryID:    "anime",
+			Title:        "住在拔作岛上的我应该如何是好？",
+			Path:         `/media/影视库/动漫/拔作岛/[64bitsub][Nukitashi][01][AVC_2×FLAC].mkv.strm`,
+			SeasonNum:    1,
+			EpisodeNum:   1,
+			ScrapeStatus: "matched",
+		},
+		{
+			Base:         model.Base{ID: "main-2"},
+			LibraryID:    "anime",
+			Title:        "住在拔作岛上的我应该如何是好？",
+			Path:         `/media/影视库/动漫/拔作岛/[64bitsub][Nukitashi][02][AVC_2×FLAC].mkv.strm`,
+			SeasonNum:    1,
+			EpisodeNum:   2,
+			ScrapeStatus: "matched",
+		},
+		{
+			Base:         model.Base{ID: "special-1"},
+			LibraryID:    "anime",
+			Title:        "nukitashi",
+			Path:         `/media/影视库/动漫/拔作岛/[64bitsub][Nukitashi][CM_01][AVC_FLAC].mkv.strm`,
+			ScrapeStatus: "matched",
+		},
+		{
+			Base:         model.Base{ID: "special-2"},
+			LibraryID:    "anime",
+			Title:        "nukitashi",
+			Path:         `/media/影视库/动漫/拔作岛/[64bitsub][Nukitashi][PV_01][AVC_FLAC].mkv.strm`,
+			ScrapeStatus: "matched",
+		},
+	}
+
+	cards := groupMediaSeriesCards(items)
+	if len(cards) != 1 {
+		t.Fatalf("cards=%#v, want main episodes and specials in the same directory folded into one card", cards)
+	}
+	if cards[0].Count != 4 {
+		t.Fatalf("series count=%d, want 4 items", cards[0].Count)
+	}
+}
+
 func TestGroupMediaSeriesCardsKeepsMovieVersionsAsOneMovie(t *testing.T) {
 	items := []model.Media{
 		{
@@ -410,15 +455,19 @@ func TestGroupMediaSeriesCardsKeepsTheatricalMovieWithTVSeries(t *testing.T) {
 		LibraryID:  "anime",
 		Title:      "摇曳露营△",
 		Path:       `/media/动漫/摇曳露营△ (2018)/Season 01/摇曳露营△.S01E01.mkv`,
+		PosterURL:  "https://image.tmdb.org/t/p/w500/episode.jpg",
 		SeasonNum:  1,
 		EpisodeNum: 1,
 	}
 	theatrical := model.Media{
-		Base:      model.Base{ID: "theatrical"},
-		LibraryID: "anime",
-		Title:     "摇曳露营△ 剧场版",
-		Path:      `/media/动漫/摇曳露营△ (2018)/摇曳露营△ 剧场版 (2022)/Eiga.Yurukyan.2022.Bluray.mkv`,
-		TMDbID:    566466,
+		Base:        model.Base{ID: "theatrical"},
+		LibraryID:   "anime",
+		Title:       "摇曳露营△ 剧场版",
+		Path:        `/media/动漫/摇曳露营△ (2018)/摇曳露营△ 剧场版 (2022)/Eiga.Yurukyan.2022.Bluray.mkv`,
+		PosterURL:   "/media/动漫/摇曳露营△ (2018)/剧场版/poster.jpg",
+		BackdropURL: "/media/动漫/摇曳露营△ (2018)/剧场版/background.jpg",
+		Overview:    "剧场版简介",
+		TMDbID:      566466,
 	}
 
 	cards := groupMediaSeriesCards([]model.Media{episode, theatrical})
@@ -428,6 +477,12 @@ func TestGroupMediaSeriesCardsKeepsTheatricalMovieWithTVSeries(t *testing.T) {
 	if cards[0].Count != 2 {
 		t.Fatalf("series card count=%d, want TV episode plus theatrical movie", cards[0].Count)
 	}
+	if cards[0].Rep.ID != episode.ID {
+		t.Fatalf("series representative=%q, want TV episode %q", cards[0].Rep.ID, episode.ID)
+	}
+	if cards[0].Rep.Title != episode.Title {
+		t.Fatalf("series representative title=%q, want %q", cards[0].Rep.Title, episode.Title)
+	}
 }
 
 func TestGroupMediaSeriesCardsDoesNotCollideMovieAndTVExternalIDs(t *testing.T) {
@@ -493,11 +548,11 @@ func TestGroupMediaSeriesCardsKeepsIndependentMoviesSeparateInSharedSubdirectory
 		{LibraryID: "movies", Title: "cd1", Path: `/media/电影/指环王 (2001)/cd1.mkv`},
 		{LibraryID: "movies", Title: "cd2", Path: `/media/电影/指环王 (2001)/cd2.mkv`},
 	}
-		cdCards := groupMediaSeriesCards(cdItems)
-		if len(cdCards) != 1 {
-			t.Fatalf("got %d cards for cd1/cd2, want 1 folded movie card", len(cdCards))
-		}
+	cdCards := groupMediaSeriesCards(cdItems)
+	if len(cdCards) != 1 {
+		t.Fatalf("got %d cards for cd1/cd2, want 1 folded movie card", len(cdCards))
 	}
+}
 
 func TestListMediaEpisodesKeepsIndependentMoviesSeparate(t *testing.T) {
 	db := newServiceTestDB(t, &model.Library{}, &model.Media{})

internal/service/organizer_sidecar.go

@@ -43,7 +43,7 @@ var artworkSidecarSuffixes = []string{
 // artworkSidecarExtensions are the image extensions a sidecar may use. Both
 // "base-poster.jpg" (bare separator) and "base.poster.jpg" (dotted separator)
 // rely on suffix matching, so we probe the common image extensions.
-var artworkSidecarExtensions = []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn"}
+var artworkSidecarExtensions = []string{".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tbn", ".img"}
 
 // transferSidecarArtwork moves/copies/links the scraped poster/backdrop
 // sidecar files alongside its media using the same transfer mode, mirroring

internal/service/scanner_local_ingest.go

@@ -200,7 +200,7 @@ func (s *ScannerService) writeLocalScanMedia(in localScanWriteInput) {
 		in.writeBatch.AddWithAfter(in.path, in.media, in.after)
 		return
 	}
-	if err := s.repo.Media.Upsert(in.ctx, in.media); err != nil {
+	if err := s.repo.Media.UpsertWithAliases(in.ctx, in.media, missingSTRMPathAliases(in.path)); err != nil {
 		addScanError(in.res, in.path, err)
 		s.log.Warn("upsert media failed", zap.String("path", in.path), zap.Error(err))
 		return
@@ -252,8 +252,10 @@ func (s *ScannerService) duplicateByFileID(ctx context.Context, fileID, path str
 }
 
 func (s *ScannerService) mediaPathExists(ctx context.Context, path string) bool {
+	paths := []string{path}
+	paths = append(paths, missingSTRMPathAliases(path)...)
 	var count int64
 	err := s.repo.DB.WithContext(ctx).Unscoped().Model(&model.Media{}).
-		Where("path = ?", path).Count(&count).Error
+		Where("path IN ?", paths).Count(&count).Error
 	return err == nil && count > 0
 }

internal/service/scanner_local_write_batch.go

@@ -7,6 +7,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
 )
 
 type localMediaWriteBatch struct {
@@ -18,9 +19,10 @@ type localMediaWriteBatch struct {
 }
 
 type localMediaWriteItem struct {
-	path  string
-	media *model.Media
-	after func()
+	path    string
+	media   *model.Media
+	aliases []string
+	after   func()
 }
 
 func newLocalMediaWriteBatch(scanner *ScannerService, ctx context.Context, res *ScanResult, limit int) *localMediaWriteBatch {
@@ -41,7 +43,12 @@ func (b *localMediaWriteBatch) AddWithAfter(path string, media *model.Media, aft
 	if media.ScrapeStatus == "" {
 		media.ScrapeStatus = "pending"
 	}
-	b.items = append(b.items, localMediaWriteItem{path: path, media: media, after: after})
+	b.items = append(b.items, localMediaWriteItem{
+		path:    path,
+		media:   media,
+		aliases: missingSTRMPathAliases(path),
+		after:   after,
+	})
 	if len(b.items) >= b.limit {
 		b.Flush()
 	}
@@ -53,39 +60,35 @@ func (b *localMediaWriteBatch) Flush() {
 	}
 	items := b.items
 	b.items = nil
-	media := make([]model.Media, 0, len(items))
-	for _, item := range items {
-		if item.media != nil {
-			media = append(media, *item.media)
-		}
-	}
-	if len(media) == 0 {
-		return
-	}
-	existingPaths := b.existingPaths(items)
-	upsertItems := make([]*model.Media, 0, len(items))
-	upsertAfter := make([]func(), 0, len(items))
+
+	existingPaths, lookupOK := b.existingPathOrAliasSet(items)
+	upsertItems := make([]localMediaWriteItem, 0, len(items))
 	createItems := make([]localMediaWriteItem, 0, len(items))
-	createMedia := make([]model.Media, 0, len(items))
 	for _, item := range items {
 		if item.media == nil {
 			continue
 		}
-		if existingPaths[filepath.Clean(item.media.Path)] {
-			// 已存在行：攒起来在一个事务里逐条 upsert（一批一次提交）。
-			after := item.after
-			upsertItems = append(upsertItems, item.media)
-			upsertAfter = append(upsertAfter, after)
+		// If the alias lookup failed, route through UpsertWithAliases instead of
+		// direct-create. That is slower but cannot create a duplicate row.
+		if !lookupOK || mediaPathOrAliasExists(item.media.Path, item.aliases, existingPaths) {
+			upsertItems = append(upsertItems, item)
 			continue
 		}
 		createItems = append(createItems, item)
-		createMedia = append(createMedia, *item.media)
 	}
-	b.flushUpserts(items, upsertItems, upsertAfter)
-	if len(createMedia) == 0 {
+
+	b.flushUpserts(upsertItems)
+	if len(createItems) == 0 {
 		b.publish()
 		return
 	}
+
+	createMedia := make([]model.Media, 0, len(createItems))
+	for _, item := range createItems {
+		if item.media != nil {
+			createMedia = append(createMedia, *item.media)
+		}
+	}
 	if err := b.scanner.repo.DB.WithContext(b.ctx).CreateInBatches(&createMedia, b.limit).Error; err == nil {
 		b.res.Added += len(createMedia)
 		for _, item := range createItems {
@@ -96,12 +99,13 @@ func (b *localMediaWriteBatch) Flush() {
 		b.publish()
 		return
 	}
+
 	for _, item := range createItems {
 		if item.media == nil {
 			continue
 		}
 		wasExisting := b.mediaPathExists(item.media.Path)
-		if err := b.scanner.repo.Media.Upsert(b.ctx, item.media); err != nil {
+		if err := b.scanner.repo.Media.UpsertWithAliases(b.ctx, item.media, item.aliases); err != nil {
 			addScanError(b.res, item.path, err)
 			b.scanner.log.Warn("upsert media failed", zap.String("path", item.path), zap.Error(err))
 			continue
@@ -118,47 +122,90 @@ func (b *localMediaWriteBatch) Flush() {
 	b.publish()
 }
 
-func (b *localMediaWriteBatch) existingPaths(items []localMediaWriteItem) map[string]bool {
+// existingPathOrAliasSet loads exact and alias paths in bounded query chunks. Aliases
+// have already been filtered against the filesystem by AddWithAfter, so an
+// existing keep_ext sibling is never treated as a rename.
+func (b *localMediaWriteBatch) existingPathOrAliasSet(items []localMediaWriteItem) (map[string]bool, bool) {
 	out := map[string]bool{}
 	if b == nil || b.scanner == nil || b.scanner.repo == nil || b.scanner.repo.DB == nil || len(items) == 0 {
-		return out
+		return out, false
+	}
+	seen := make(map[string]struct{}, len(items)*2)
+	paths := make([]string, 0, len(items)*2)
+	add := func(path string) {
+		path = filepath.Clean(path)
+		if path == "" || path == "." {
+			return
+		}
+		if _, ok := seen[path]; ok {
+			return
+		}
+		seen[path] = struct{}{}
+		paths = append(paths, path)
 	}
-	paths := make([]string, 0, len(items))
 	for _, item := range items {
 		if item.media == nil || item.media.Path == "" {
 			continue
 		}
-		paths = append(paths, item.media.Path)
+		add(item.media.Path)
+		for _, alias := range item.aliases {
+			add(alias)
+		}
 	}
 	if len(paths) == 0 {
-		return out
+		return out, true
 	}
-	var rows []string
-	if err := b.scanner.repo.DB.WithContext(b.ctx).
-		Unscoped().
-		Model(&model.Media{}).
-		Where("path IN ?", paths).
-		Pluck("path", &rows).Error; err != nil {
-		b.scanner.log.Debug("load existing media paths for scan batch failed", zap.Error(err))
-		return out
+	// Keep SQL variables below the legacy SQLite limit (999). A batch can
+	// contain 100 STRM rows and every row has many sibling aliases.
+	const pathLookupChunk = 400
+	for start := 0; start < len(paths); start += pathLookupChunk {
+		end := start + pathLookupChunk
+		if end > len(paths) {
+			end = len(paths)
+		}
+		var rows []string
+		if err := b.scanner.repo.DB.WithContext(b.ctx).
+			Unscoped().
+			Model(&model.Media{}).
+			Where("path IN ?", paths[start:end]).
+			Pluck("path", &rows).Error; err != nil {
+			b.scanner.log.Debug("load existing media paths for scan batch failed", zap.Error(err))
+			return nil, false
+		}
+		for _, path := range rows {
+			out[filepath.Clean(path)] = true
+		}
 	}
-	for _, path := range rows {
-		out[filepath.Clean(path)] = true
-	}
-	return out
+	return out, true
 }
 
-// flushUpserts 把已存在行的 upsert 攒成一个事务（一次提交/一组 fsync）。
-// 整批失败（如单条数据触发约束）时退回逐条 Upsert，只丢真正坏的那几条。
-func (b *localMediaWriteBatch) flushUpserts(allItems []localMediaWriteItem, upsertItems []*model.Media, upsertAfter []func()) {
+func mediaPathOrAliasExists(path string, aliases []string, existing map[string]bool) bool {
+	if existing[filepath.Clean(path)] {
+		return true
+	}
+	for _, alias := range aliases {
+		if existing[filepath.Clean(alias)] {
+			return true
+		}
+	}
+	return false
+}
+
+// flushUpserts 把已存在或可迁移路径的行攒成一个事务（一次提交/一组 fsync）。
+// 整批失败（如单条数据触发约束）时退回逐条 upsert，只丢真正坏的那几条。
+func (b *localMediaWriteBatch) flushUpserts(upsertItems []localMediaWriteItem) {
 	if len(upsertItems) == 0 {
 		return
 	}
-	if err := b.scanner.repo.Media.UpsertBatch(b.ctx, upsertItems); err == nil {
+	batchItems := make([]repository.MediaUpsertItem, 0, len(upsertItems))
+	for _, item := range upsertItems {
+		batchItems = append(batchItems, repository.MediaUpsertItem{Media: item.media, AliasPaths: item.aliases})
+	}
+	if err := b.scanner.repo.Media.UpsertBatchWithAliases(b.ctx, batchItems); err == nil {
 		b.res.Updated += len(upsertItems)
-		for _, after := range upsertAfter {
-			if after != nil {
-				after()
+		for _, item := range upsertItems {
+			if item.after != nil {
+				item.after()
 			}
 		}
 		return
@@ -166,13 +213,7 @@ func (b *localMediaWriteBatch) flushUpserts(allItems []localMediaWriteItem, upse
 		b.scanner.log.Warn("batch upsert failed; falling back to per-item upsert",
 			zap.Int("items", len(upsertItems)))
 	}
-	// 兜底：按原始顺序找回每个条目的 path/after（两个切片同序但可能含 nil）。
-	idx := 0
-	for _, item := range allItems {
-		if item.media == nil || idx >= len(upsertItems) || upsertItems[idx] != item.media {
-			continue
-		}
-		idx++
+	for _, item := range upsertItems {
 		b.upsertExistingItem(item)
 	}
 }
@@ -181,7 +222,7 @@ func (b *localMediaWriteBatch) upsertExistingItem(item localMediaWriteItem) {
 	if item.media == nil {
 		return
 	}
-	if err := b.scanner.repo.Media.Upsert(b.ctx, item.media); err != nil {
+	if err := b.scanner.repo.Media.UpsertWithAliases(b.ctx, item.media, item.aliases); err != nil {
 		addScanError(b.res, item.path, err)
 		b.scanner.log.Warn("upsert media failed", zap.String("path", item.path), zap.Error(err))
 		return

internal/service/scanner_prune.go

@@ -5,13 +5,15 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
 
 	"go.uber.org/zap"
 
 	"github.com/truewhile/MeBox/internal/model"
 )
 
-// RemovePath 物理删除磁盘上已不存在的媒体记录。
+// RemovePath 移除磁盘上已不存在的媒体记录。普通的删除仍做物理删除；
+// 可确认是 STRM 扩展名改名的路径则先保留软删除墓碑，供后续 ingest 继承元数据。
 func (s *ScannerService) RemovePath(ctx context.Context, path string) (int64, error) {
 	if _, err := os.Stat(path); err == nil {
 		return 0, nil // still exists; nothing to remove
@@ -30,24 +32,64 @@ func (s *ScannerService) RemovePath(ctx context.Context, path string) (int64, er
 		Find(&rows).Error; err != nil {
 		return 0, err
 	}
-	ids := make([]string, 0, len(rows))
+	softIDs := make([]string, 0, len(rows))
+	hardIDs := make([]string, 0, len(rows))
 	for _, row := range rows {
 		// LIKE 里的 % _ 是通配符（候选集只会偏大），用 Go 前缀精确过滤，
 		// 避免对含 % / _ 的路径误删。
-		if row.Path == path || strings.HasPrefix(filepath.Clean(row.Path), prefix) {
-			ids = append(ids, row.ID)
+		if row.Path != path && !strings.HasPrefix(filepath.Clean(row.Path), prefix) {
+			continue
 		}
+		// A vanished STRM with a live sibling (foo.strm <-> foo.mkv.strm)
+		// is a rename. Keep a soft-deleted tombstone so the later ingest can
+		// adopt its ID and scraped metadata even if fsnotify delivers the
+		// remove event before the create event. A true deletion stays hard.
+		if row.Path == path && liveSTRMPathAlias(path) {
+			softIDs = append(softIDs, row.ID)
+			continue
+		}
+		hardIDs = append(hardIDs, row.ID)
 	}
-	if len(ids) == 0 {
-		return 0, nil
+	var removed int64
+	if len(softIDs) > 0 {
+		res := s.repo.DB.WithContext(ctx).
+			Where("id IN ?", softIDs).
+			Delete(&model.Media{})
+		if res.Error != nil {
+			return removed, res.Error
+		}
+		removed += res.RowsAffected
 	}
-	res := s.repo.DB.WithContext(ctx).Unscoped().
-		Where("id IN ?", ids).
-		Delete(&model.Media{})
-	if res.Error == nil && res.RowsAffected > 0 {
+	if len(hardIDs) > 0 {
+		res := s.repo.DB.WithContext(ctx).Unscoped().
+			Where("id IN ?", hardIDs).
+			Delete(&model.Media{})
+		if res.Error != nil {
+			return removed, res.Error
+		}
+		removed += res.RowsAffected
+	}
+	if removed > 0 {
 		s.invalidateMediaCache(ctx)
 	}
-	return res.RowsAffected, res.Error
+	if len(softIDs) > 0 {
+		s.purgeExpiredSTRMTombstones(ctx)
+	}
+	return removed, nil
+}
+
+const strmRenameTombstoneRetention = 7 * 24 * time.Hour
+
+// purgeExpiredSTRMTombstones keeps the soft-delete grace period bounded.
+// It is deliberately restricted to deleted media rows under a STRM alias
+// workflow; normal deletions are still hard-deleted immediately.
+func (s *ScannerService) purgeExpiredSTRMTombstones(ctx context.Context) {
+	cutoff := time.Now().Add(-strmRenameTombstoneRetention)
+	if err := s.repo.DB.WithContext(ctx).Unscoped().
+		Where("deleted_at IS NOT NULL AND deleted_at < ? AND path LIKE ?", cutoff, "%.strm").
+		Delete(&model.Media{}).Error; err != nil && s.log != nil {
+		s.log.Warn("purge expired STRM rename tombstones failed", zap.Error(err))
+	}
 }
 
 func (s *ScannerService) pruneMissingMedia(ctx context.Context, libraryID string, seen map[string]struct{}) (int64, error) {

internal/service/scanner_scan.go

@@ -117,6 +117,10 @@ func (s *ScannerService) scanLibrary(ctx context.Context, libraryID string, auto
 			}
 			continue
 		}
+		// Flush alias-aware upserts before pruning missing paths. This lets a
+		// foo.strm <-> foo.mkv.strm rename migrate the existing row (including
+		// scraped metadata) instead of deleting it as "old path missing".
+		writeBatch.Flush()
 		scannedRoots++
 		removed, err := s.pruneMissingMediaForRoot(ctx, lib.ID, root.ID, root.Path, seen)
 		if err != nil {

internal/service/scanner_strm_rename_test.go

@@ -0,0 +1,212 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func TestSTRMPathAliasesCoverBothKeepExtDirections(t *testing.T) {
+	toKeepExt := strmPathAliases(filepath.Join(t.TempDir(), "Show.S01E01.strm"))
+	if !containsPathAlias(toKeepExt, "Show.S01E01.mkv.strm") {
+		t.Fatalf("missing keep_ext alias: %#v", toKeepExt)
+	}
+	fromKeepExt := strmPathAliases(filepath.Join(t.TempDir(), "Show.S01E01.mkv.strm"))
+	if !containsPathAlias(fromKeepExt, "Show.S01E01.strm") {
+		t.Fatalf("missing stripped alias: %#v", fromKeepExt)
+	}
+}
+
+func TestMissingSTRMPathAliasesKeepsRealKeepExtSiblingVersions(t *testing.T) {
+	dir := t.TempDir()
+	current := filepath.Join(dir, "Show.S01E01.mkv.strm")
+	sibling := filepath.Join(dir, "Show.S01E01.mp4.strm")
+	writeFileContent(t, current, "https://example.test/mkv")
+	writeFileContent(t, sibling, "https://example.test/mp4")
+
+	aliases := missingSTRMPathAliases(current)
+	if containsPathAlias(aliases, sibling) {
+		t.Fatalf("existing keep_ext sibling must remain a separate version: %#v", aliases)
+	}
+}
+
+func TestScanLibraryMigratesSTRMKeepExtRename(t *testing.T) {
+	cases := []struct {
+		name    string
+		oldName string
+		newName string
+	}{
+		{name: "add video extension", oldName: "Show.S01E01.strm", newName: "Show.S01E01.mkv.strm"},
+		{name: "remove video extension", oldName: "Show.S01E01.mkv.strm", newName: "Show.S01E01.strm"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			sc, repos := newScannerTestEnv(t)
+			root := t.TempDir()
+			lib := model.Library{Name: "Anime", Path: root, Type: "anime", Enabled: true}
+			if err := repos.Library.Create(t.Context(), &lib); err != nil {
+				t.Fatal(err)
+			}
+			oldPath := filepath.Join(root, tc.oldName)
+			newPath := filepath.Join(root, tc.newName)
+			writeFileContent(t, oldPath, "https://example.test/video")
+			if _, err := sc.IngestPath(t.Context(), lib.ID, oldPath); err != nil {
+				t.Fatal(err)
+			}
+
+			var before model.Media
+			if err := repos.DB.First(&before, "path = ?", oldPath).Error; err != nil {
+				t.Fatal(err)
+			}
+			if err := repos.DB.Model(&model.Media{}).Where("id = ?", before.ID).Updates(map[string]any{
+				"title":         "地狱乐",
+				"original_name": "Jigokuraku",
+				"overview":      "preserved overview",
+				"poster_url":    "Jigokuraku-poster.jpg",
+				"backdrop_url":  "Jigokuraku-backdrop.jpg",
+				"year":          2023,
+				"rating":        8.6,
+				"tm_db_id":      12345,
+				"bangumi_id":    67890,
+				"genres":        "Action,Adventure",
+				"scrape_status": "matched",
+			}).Error; err != nil {
+				t.Fatal(err)
+			}
+			if err := os.Rename(oldPath, newPath); err != nil {
+				t.Fatal(err)
+			}
+
+			res, err := sc.ScanLibrary(t.Context(), lib.ID)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if res.ErrorCount != 0 {
+				t.Fatalf("scan errors: %#v", res.Errors)
+			}
+			if got := countMedia(t, repos); got != 1 {
+				t.Fatalf("media count = %d, want 1", got)
+			}
+
+			var after model.Media
+			if err := repos.DB.First(&after, "id = ?", before.ID).Error; err != nil {
+				t.Fatalf("old media row was not preserved: %v", err)
+			}
+			if after.Path != newPath {
+				t.Fatalf("path = %q, want %q", after.Path, newPath)
+			}
+			if after.Title != "地狱乐" || after.OriginalName != "Jigokuraku" || after.Overview != "preserved overview" {
+				t.Fatalf("scraped identity metadata was lost: %#v", after)
+			}
+			if after.PosterURL != "Jigokuraku-poster.jpg" || after.BackdropURL != "Jigokuraku-backdrop.jpg" {
+				t.Fatalf("artwork was lost: poster=%q backdrop=%q", after.PosterURL, after.BackdropURL)
+			}
+			if after.TMDbID != 12345 || after.BangumiID != 67890 || after.ScrapeStatus != "matched" {
+				t.Fatalf("scrape IDs/status changed: tmdb=%d bgm=%d status=%q", after.TMDbID, after.BangumiID, after.ScrapeStatus)
+			}
+		})
+	}
+}
+
+func TestIngestPathAdoptsSoftDeletedSTRMRenameTombstone(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	lib := model.Library{Name: "Anime", Path: root, Type: "anime", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	oldPath := filepath.Join(root, "Show.S01E01.mkv.strm")
+	newPath := filepath.Join(root, "Show.S01E01.strm")
+	writeFileContent(t, oldPath, "https://example.test/video")
+	if _, err := sc.IngestPath(t.Context(), lib.ID, oldPath); err != nil {
+		t.Fatal(err)
+	}
+
+	var before model.Media
+	if err := repos.DB.First(&before, "path = ?", oldPath).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.DB.Model(&model.Media{}).Where("id = ?", before.ID).Updates(map[string]any{
+		"title":         "拔作岛",
+		"overview":      "kept through remove-before-create",
+		"poster_url":    "nukitashi-poster.webp",
+		"tm_db_id":      222,
+		"scrape_status": "matched",
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Rename(oldPath, newPath); err != nil {
+		t.Fatal(err)
+	}
+
+	// Simulate fsnotify delivering Remove(old) before Create(new).
+	if removed, err := sc.RemovePath(t.Context(), oldPath); err != nil || removed != 1 {
+		t.Fatalf("RemovePath() removed=%d err=%v, want 1", removed, err)
+	}
+	var tombstone model.Media
+	if err := repos.DB.Unscoped().First(&tombstone, "id = ?", before.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if !tombstone.DeletedAt.Valid {
+		t.Fatal("rename tombstone should be soft-deleted")
+	}
+	if got := countMedia(t, repos); got != 0 {
+		t.Fatalf("active media count = %d, want 0 before create event", got)
+	}
+
+	if _, err := sc.IngestPath(t.Context(), lib.ID, newPath); err != nil {
+		t.Fatal(err)
+	}
+	var after model.Media
+	if err := repos.DB.First(&after, "id = ?", before.ID).Error; err != nil {
+		t.Fatalf("soft-deleted row was not restored: %v", err)
+	}
+	if after.Path != newPath || after.Title != "拔作岛" || after.Overview != "kept through remove-before-create" {
+		t.Fatalf("rename metadata was not adopted: %#v", after)
+	}
+	if after.TMDbID != 222 || after.ScrapeStatus != "matched" {
+		t.Fatalf("scrape metadata changed: tmdb=%d status=%q", after.TMDbID, after.ScrapeStatus)
+	}
+	if got := countMedia(t, repos); got != 1 {
+		t.Fatalf("media count = %d, want 1", got)
+	}
+}
+
+func TestRemovePathStillHardDeletesTrueDeletionWithoutAlias(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	lib := model.Library{Name: "Anime", Path: root, Type: "anime", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(root, "Deleted.S01E01.mkv.strm")
+	writeFileContent(t, path, "https://example.test/video")
+	if _, err := sc.IngestPath(t.Context(), lib.ID, path); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Remove(path); err != nil {
+		t.Fatal(err)
+	}
+	if removed, err := sc.RemovePath(t.Context(), path); err != nil || removed != 1 {
+		t.Fatalf("RemovePath() removed=%d err=%v, want 1", removed, err)
+	}
+	var count int64
+	if err := repos.DB.Unscoped().Model(&model.Media{}).Where("path = ?", path).Count(&count).Error; err != nil {
+		t.Fatal(err)
+	}
+	if count != 0 {
+		t.Fatalf("true deletion left %d tombstone row(s)", count)
+	}
+}
+
+func containsPathAlias(paths []string, name string) bool {
+	for _, path := range paths {
+		if strings.EqualFold(filepath.Base(path), filepath.Base(name)) {
+			return true
+		}
+	}
+	return false
+}

internal/service/scraper_query_test.go

@@ -48,6 +48,17 @@ func TestCleanQuery(t *testing.T) {
 	}
 }
 
+func TestCleanQueryIgnoresKeepExtSTRMSuffix(t *testing.T) {
+	plain := filepath.Join("/media/anime", "Jigokuraku 2023 S01E14.strm")
+	keepExt := filepath.Join("/media/anime", "Jigokuraku 2023 S01E14.mkv.strm")
+	plainTitle, plainYear := CleanQuery(plain)
+	keepTitle, keepYear := CleanQuery(keepExt)
+	if plainTitle != keepTitle || plainYear != keepYear {
+		t.Fatalf("keep_ext changed scrape identity: plain=(%q,%d) keep_ext=(%q,%d)",
+			plainTitle, plainYear, keepTitle, keepYear)
+	}
+}
+
 func TestScrapeQueryCandidatesCleanDirtySeriesFolder(t *testing.T) {
 	lib := &model.Library{
 		Path: `F:\media\电视剧\欧美剧`,

internal/service/strm_service.go

@@ -49,7 +49,7 @@ const (
 
 const (
 	StrmDefaultVideoExt = "mkv,mp4,avi,rmvb,rm,mov,ts,wmv,flv,m4v,iso,mpg,mpeg,webm"
-	StrmDefaultMetaExt  = "nfo,jpg,jpeg,png,srt,ass,ssa,sub,txt,bmp,webp"
+	StrmDefaultMetaExt  = "nfo,jpg,jpeg,png,srt,ass,ssa,sub,txt,bmp,webp,img"
 	StrmDefaultExclude  = "sample,trailer,预告"
 )
 

internal/service/strm_sync.go

@@ -612,6 +612,12 @@ func (st *strmSyncState) isVideoExt(ext string, size int64) bool {
 }
 
 func (st *strmSyncState) isMetaExt(ext string) bool {
+	// Legacy MeBox installs may have persisted strm.meta_ext without img.
+	// .img is emitted by the artwork writer as a fallback image container, so
+	// keep accepting existing sidecars without requiring a settings migration.
+	if strings.EqualFold(ext, ".img") {
+		return true
+	}
 	for _, e := range st.cfg.MetaExt {
 		if "."+e == ext {
 			return true

internal/service/strm_sync_test.go

@@ -1680,3 +1680,10 @@ func TestHandleVideoKeepExtWritesAllVersions(t *testing.T) {
 		t.Fatalf("NewStrm=%d want 2", st.rec.NewStrm)
 	}
 }
+
+func TestStrmSyncTreatsLegacyImgAsMetadata(t *testing.T) {
+	st := &strmSyncState{cfg: &strmPathConfig{MetaExt: csvSplit("nfo,jpg")}}
+	if !st.isMetaExt(".img") {
+		t.Fatal("legacy .img sidecars must remain metadata even when an old setting omits img")
+	}
+}

internal/service/subtitle.go

@@ -234,7 +234,7 @@ func discoverExternalSubtitleTracks(m *model.Media) []SubtitleTrack {
 				Path:     filepath.Join(c, e.Name()),
 				Codec:    codec,
 				Source:   "external",
-				Delivery: "webvtt",
+				Delivery: subtitleDeliveryForCodec(codec),
 			})
 		}
 	}
@@ -297,6 +297,18 @@ func (s *SubtitleService) discoverEmbedded(ctx context.Context, media *model.Med
 	return subtitleTracksFromProbe(probe), nil
 }
 
+// subtitleDeliveryForCodec selects the browser rendering path for a text
+// subtitle codec. ASS/SSA keep their original bytes and are rendered by
+// libass in the web player; other text formats are converted to WebVTT.
+func subtitleDeliveryForCodec(codec string) string {
+	switch strings.ToLower(strings.TrimSpace(codec)) {
+	case "ass", "ssa":
+		return "ass"
+	default:
+		return "webvtt"
+	}
+}
+
 func subtitleTracksFromProbe(probe embeddedSubtitleProbe) []SubtitleTrack {
 	tracks := make([]SubtitleTrack, 0, len(probe.Streams))
 	for _, stream := range probe.Streams {
@@ -314,7 +326,7 @@ func subtitleTracksFromProbe(probe embeddedSubtitleProbe) []SubtitleTrack {
 		} else if stream.Disposition.Default != 0 {
 			label += "（默认）"
 		}
-		delivery := "webvtt"
+		delivery := subtitleDeliveryForCodec(codec)
 		if imageSubtitleCodecs[codec] {
 			delivery = "burn"
 		}
@@ -464,6 +476,9 @@ func (s *SubtitleService) ServeRaw(ctx context.Context, mediaID, sub string, w i
 	if err != nil || m == nil {
 		return errors.New("media not found")
 	}
+	if strings.HasPrefix(sub, "embedded:") {
+		return errors.New("embedded subtitle is not available in raw mode")
+	}
 	abs, err := filepath.Abs(sub)
 	if err != nil {
 		return err
@@ -472,6 +487,9 @@ func (s *SubtitleService) ServeRaw(ctx context.Context, mediaID, sub string, w i
 	if !pathWithin(abs, mediaDir) {
 		return fmt.Errorf("path escape")
 	}
+	if _, ok := extToCodec[strings.ToLower(filepath.Ext(abs))]; !ok {
+		return errors.New("unsupported subtitle format")
+	}
 	f, err := os.Open(abs) // #nosec G304 -- abs is constrained to the media file directory with pathWithin.
 	if err != nil {
 		return err
@@ -480,3 +498,49 @@ func (s *SubtitleService) ServeRaw(ctx context.Context, mediaID, sub string, w i
 	_, err = io.Copy(w, f)
 	return err
 }
+
+// ServeASS returns an ASS/SSA stream suitable for libass-wasm. External ASS
+// files are sent unchanged; embedded ASS/SSA tracks are remuxed to ASS by
+// ffmpeg. This keeps fonts, positioning and typesetting data available to the
+// browser renderer instead of flattening the track through assToVTT first.
+func (s *SubtitleService) ServeASS(ctx context.Context, mediaID, sub string, w io.Writer) error {
+	m, err := s.repo.Media.FindByID(ctx, mediaID)
+	if err != nil || m == nil {
+		return errors.New("media not found")
+	}
+	if strings.HasPrefix(sub, "embedded:") {
+		index, err := strconv.Atoi(strings.TrimPrefix(sub, "embedded:"))
+		if err != nil || index < 0 {
+			return errors.New("invalid embedded subtitle")
+		}
+		return s.serveEmbeddedASS(ctx, m, index, w)
+	}
+	switch strings.ToLower(filepath.Ext(sub)) {
+	case ".ass", ".ssa":
+		return s.ServeRaw(ctx, mediaID, sub, w)
+	default:
+		return errors.New("subtitle is not ASS/SSA")
+	}
+}
+
+func (s *SubtitleService) serveEmbeddedASS(ctx context.Context, media *model.Media, streamIndex int, w io.Writer) error {
+	input, err := s.resolveInput(ctx, media)
+	if err != nil {
+		return err
+	}
+	bin, err := resolveLocalExecutable(s.cfg.App.FFmpegPath, "ffmpeg")
+	if err != nil {
+		return err
+	}
+	args := []string{"-hide_banner", "-loglevel", "error"}
+	args = append(args, ffmpegHTTPInputArgs(input)...)
+	args = append(args, "-i", input.Source, "-map", "0:"+strconv.Itoa(streamIndex), "-c:s", "ass", "-f", "ass", "-")
+	cmd := exec.CommandContext(ctx, bin, args...) // #nosec G204 -- executable is resolved locally and arguments do not use a shell.
+	cmd.Stdout = w
+	var stderr strings.Builder
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("extract embedded ASS subtitle: %w: %s", err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}

internal/service/subtitle_test.go

@@ -100,7 +100,7 @@ func TestEmbeddedSubtitleProbeClassifiesTextAndBitmapTracks(t *testing.T) {
 	if len(tracks) != 2 {
 		t.Fatalf("len(tracks) = %d, want 2", len(tracks))
 	}
-	if tracks[0].Delivery != "webvtt" || tracks[0].Path != "embedded:2" {
+	if tracks[0].Delivery != "ass" || tracks[0].Path != "embedded:2" {
 		t.Fatalf("text track = %#v", tracks[0])
 	}
 	if tracks[1].Delivery != "burn" || tracks[1].StreamIndex != 4 {
@@ -108,6 +108,18 @@ func TestEmbeddedSubtitleProbeClassifiesTextAndBitmapTracks(t *testing.T) {
 	}
 }
 
+func TestSubtitleDeliveryClassifiesASSForLibass(t *testing.T) {
+	if got := subtitleDeliveryForCodec("ass"); got != "ass" {
+		t.Fatalf("ass delivery = %q, want ass", got)
+	}
+	if got := subtitleDeliveryForCodec("ssa"); got != "ass" {
+		t.Fatalf("ssa delivery = %q, want ass", got)
+	}
+	if got := subtitleDeliveryForCodec("subrip"); got != "webvtt" {
+		t.Fatalf("subrip delivery = %q, want webvtt", got)
+	}
+}
+
 func TestNormaliseTimecode(t *testing.T) {
 	cases := map[string]string{
 		"0:00:01":       "00:00:01",
@@ -176,4 +188,17 @@ func TestSubtitleServeRawWritesSourceBytes(t *testing.T) {
 	if got := buf.String(); got != raw {
 		t.Fatalf("ServeRaw returned %q, want raw %q", got, raw)
 	}
+
+	buf.Reset()
+	if err := svc.ServeASS(t.Context(), media.ID, subPath, &buf); err != nil {
+		t.Fatal(err)
+	}
+	if got := buf.String(); got != raw {
+		t.Fatalf("ServeASS returned %q, want raw ASS %q", got, raw)
+	}
+
+	buf.Reset()
+	if err := svc.ServeRaw(t.Context(), media.ID, videoPath, &buf); err == nil {
+		t.Fatal("ServeRaw accepted a non-subtitle file")
+	}
 }

web/package-lock.json

@@ -13,6 +13,7 @@
         "danmu": "^0.20.0",
         "framer-motion": "^12.38.0",
         "hls.js": "^1.5.11",
+        "jassub": "^2.5.16",
         "lucide-react": "^0.379.0",
         "opencc-js": "^1.4.2",
         "qrcode": "^1.5.4",
@@ -1753,6 +1754,12 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/abslink": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/abslink/-/abslink-1.2.2.tgz",
+      "integrity": "sha512-HCOItvzORPjMzddCmEpbH8+W1VM3yjH+CR7DLtxlxFKX/jz5twJbm7KLfblO7eKLnXINLah8Hk2ZAJqxXeSkOg==",
+      "license": "Apache-2.0"
+    },
     "node_modules/acorn": {
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
@@ -3108,6 +3115,18 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/jassub": {
+      "version": "2.5.16",
+      "resolved": "https://registry.npmjs.org/jassub/-/jassub-2.5.16.tgz",
+      "integrity": "sha512-n4vjXfraf3o8k3/5TK6DhCYVcbQ/VqhVOgwqLd3l0xfMtsN4fpE/hPq2hPaGagBTOtJS9yHwRoRp3mmchQ9XVg==",
+      "license": "LGPL-2.1-or-later AND (FTL OR GPL-2.0-or-later) AND MIT AND MIT-Modern-Variant AND ISC AND NTP AND Zlib AND BSL-1.0",
+      "dependencies": {
+        "abslink": "^1.2.2",
+        "lfa-ponyfill": "^1.1.0",
+        "rvfc-polyfill": "^1.0.8",
+        "throughput": "^1.0.2"
+      }
+    },
     "node_modules/jiti": {
       "version": "1.21.7",
       "resolved": "https://registry.npmjs.org/jiti/-/jiti-1.21.7.tgz",
@@ -3195,6 +3214,13 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/lfa-ponyfill": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/lfa-ponyfill/-/lfa-ponyfill-1.1.1.tgz",
+      "integrity": "sha512-Had4tsGEHtIj58MRtf6SlubNDltxinxMSdxIn1GdwrWbye8TD+pZ+D6qKETnJ9+vQOfG9q/Ds4WUPskhyAMp5Q==",
+      "hasInstallScript": true,
+      "license": "MIT"
+    },
     "node_modules/lilconfig": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz",
@@ -4032,6 +4058,12 @@
         "queue-microtask": "^1.2.2"
       }
     },
+    "node_modules/rvfc-polyfill": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/rvfc-polyfill/-/rvfc-polyfill-1.0.8.tgz",
+      "integrity": "sha512-uA+0wwTkZ4OT8v45pfDfH+7Yq8mY6MvNngiF5Sq6VBgjJsvsfgt7Q18cyZqZjfAhW9rhkgXPX0cW0R9uw7yElA==",
+      "license": "GPL-3.0"
+    },
     "node_modules/scheduler": {
       "version": "0.23.2",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
@@ -4219,6 +4251,12 @@
         "node": ">=0.8"
       }
     },
+    "node_modules/throughput": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/throughput/-/throughput-1.0.2.tgz",
+      "integrity": "sha512-jvK1ZXuhsggjb3qYQjMiU/AVYYiTeqT5thWvYR2yuy2LGM84P5MSSyAinwHahGsdBYKR9m9HncVR/3f3nFKkxg==",
+      "license": "MIT"
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.16",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",

web/package.json

@@ -15,6 +15,7 @@
     "danmu": "^0.20.0",
     "framer-motion": "^12.38.0",
     "hls.js": "^1.5.11",
+    "jassub": "^2.5.16",
     "lucide-react": "^0.379.0",
     "opencc-js": "^1.4.2",
     "qrcode": "^1.5.4",

web/src/api/subtitles.ts

@@ -8,7 +8,7 @@ export interface SubtitleTrack {
   url: string
   codec: string
   source: 'external' | 'embedded'
-  delivery: 'webvtt' | 'burn'
+  delivery: 'webvtt' | 'ass' | 'burn'
   stream_index?: number
 }
 
@@ -26,4 +26,11 @@ export const subtitlesAPI = {
       path,
     )}&token=${encodeURIComponent(token)}`
   },
+
+  assUrl: (mediaId: string, path: string) => {
+    const token = useAuthStore.getState().token ?? ''
+    return `/api/subtitles/${encodeURIComponent(mediaId)}/ass?path=${encodeURIComponent(
+      path,
+    )}&token=${encodeURIComponent(token)}`
+  },
 }

web/src/assets/fonts/LICENSE-NOTO-SANS-SC.txt

@@ -0,0 +1,92 @@
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

web/src/components/AssSubtitleStage.tsx

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from 'react'
+import JASSUB from 'jassub'
+import jassubWorkerUrl from 'jassub/dist/worker/worker.js?worker&url'
+import jassubWasmUrl from 'jassub/dist/wasm/jassub-worker.wasm?url'
+import jassubModernWasmUrl from 'jassub/dist/wasm/jassub-worker-modern.wasm?url'
+import notoSansSCUrl from '../assets/fonts/noto-sans-sc-regular.woff2?url'
+
+import {
+  loadSubtitleChineseConverter,
+  type SubtitleChineseMode,
+} from '../utils/subtitleChinese'
+import { convertASSContent } from '../utils/subtitleASS'
+
+type AssSubtitleStageProps = {
+  videoRef: React.RefObject<HTMLVideoElement>
+  source: string
+  timeOffset?: number
+  chineseMode?: SubtitleChineseMode
+  onReady?: () => void
+  onError?: (error: unknown) => void
+}
+
+/**
+ * libass-wasm subtitle layer for external and embedded ASS/SSA tracks. JASSUB
+ * owns its canvas and attaches it next to the video, so this component itself
+ * renders no visible DOM nodes.
+ */
+export function AssSubtitleStage({
+  videoRef,
+  source,
+  timeOffset = 0,
+  chineseMode = 'original',
+  onReady,
+  onError,
+}: AssSubtitleStageProps) {
+  const instanceRef = useRef<JASSUB | null>(null)
+  const timeOffsetRef = useRef(timeOffset)
+  const callbacksRef = useRef({ onReady, onError })
+
+  useEffect(() => {
+    callbacksRef.current = { onReady, onError }
+  }, [onReady, onError])
+
+  useEffect(() => {
+    const video = videoRef.current
+    if (!video || !source) return
+
+    let cancelled = false
+    let instance: JASSUB | null = null
+    const controller = new AbortController()
+
+    const load = async () => {
+      try {
+        const [response, converter] = await Promise.all([
+          fetch(source, { signal: controller.signal }),
+          loadSubtitleChineseConverter(chineseMode).catch(() => (text: string) => text),
+        ])
+        if (!response.ok) throw new Error(`subtitle request failed: ${response.status}`)
+        const body = await response.text()
+        if (!body.trim()) throw new Error('empty subtitle payload')
+        if (cancelled) return
+
+        instance = new JASSUB({
+          video,
+          subContent: convertASSContent(body, converter),
+          timeOffset: timeOffsetRef.current,
+          workerUrl: jassubWorkerUrl,
+          wasmUrl: jassubWasmUrl,
+          modernWasmUrl: jassubModernWasmUrl,
+          fonts: [notoSansSCUrl],
+          defaultFont: 'Noto Sans SC',
+          queryFonts: 'local',
+          prescaleFactor: 1,
+        })
+        instanceRef.current = instance
+        await instance.ready
+        if (cancelled) {
+          void instance.destroy().catch(() => undefined)
+          return
+        }
+        callbacksRef.current.onReady?.()
+      } catch (error: unknown) {
+        if (cancelled) return
+        if (error instanceof DOMException && error.name === 'AbortError') return
+        callbacksRef.current.onError?.(error)
+      }
+    }
+
+    void load()
+
+    return () => {
+      cancelled = true
+      controller.abort()
+      instanceRef.current = null
+      if (instance) void instance.destroy().catch(() => undefined)
+    }
+    // timeOffset is applied live below. Recreating the full libass worker on a
+    // seek offset change would be unnecessarily expensive.
+  }, [source, chineseMode, videoRef])
+
+  useEffect(() => {
+    timeOffsetRef.current = timeOffset
+    if (instanceRef.current) instanceRef.current.timeOffset = timeOffset
+  }, [timeOffset])
+
+  return null
+}

web/src/components/PlayerControls.tsx

@@ -16,6 +16,12 @@ import {
 } from 'lucide-react'
 import type { SubtitleTrack } from '../api/subtitles'
 import type { SubtitleChineseMode } from '../utils/subtitleChinese'
+import {
+  SUBTITLE_POSITION_OPTIONS,
+  SUBTITLE_STYLE_OPTIONS,
+  type SubtitlePosition,
+  type SubtitleStylePreset,
+} from '../utils/subtitleDisplay'
 
 // PlayerControls — custom bottom control bar replacing the native <video
 // controls> (which cannot host custom buttons). The danmaku toggle sits right
@@ -39,6 +45,10 @@ type PlayerControlsProps = {
   onSelectSubtitle: (index: number) => void
   subtitleChineseMode: SubtitleChineseMode
   onSubtitleChineseModeChange: (mode: SubtitleChineseMode) => void
+  subtitlePosition: SubtitlePosition
+  onSubtitlePositionChange: (position: SubtitlePosition) => void
+  subtitleStyle: SubtitleStylePreset
+  onSubtitleStyleChange: (style: SubtitleStylePreset) => void
   danmakuOpen: boolean
   danmakuEnabled: boolean
   onToggleDanmaku: () => void
@@ -68,6 +78,10 @@ export function PlayerControls({
   onSelectSubtitle,
   subtitleChineseMode,
   onSubtitleChineseModeChange,
+  subtitlePosition,
+  onSubtitlePositionChange,
+  subtitleStyle,
+  onSubtitleStyleChange,
   danmakuOpen,
   danmakuEnabled,
   onToggleDanmaku,
@@ -361,7 +375,10 @@ export function PlayerControls({
   const displayTime = isScrubbing && scrubValue !== null ? scrubValue : currentTime
   const selectedSubtitle = subtitleIndex >= 0 ? subs[subtitleIndex] : undefined
   const canConvertSelectedSubtitle =
-    selectedSubtitle?.source === 'external' && selectedSubtitle.delivery === 'webvtt'
+    selectedSubtitle?.source === 'external' &&
+    (selectedSubtitle.delivery === 'webvtt' || selectedSubtitle.delivery === 'ass')
+  const canAdjustSelectedSubtitle = selectedSubtitle?.delivery === 'webvtt'
+  const usesOriginalASS = selectedSubtitle?.delivery === 'ass'
 
   return (
     <div
@@ -455,7 +472,7 @@ export function PlayerControls({
               )}
             </button>
             {subtitleMenuOpen && (
-              <div className="absolute bottom-11 right-0 z-30 min-w-44 rounded-xl border border-white/15 bg-black/85 p-1 shadow-2xl backdrop-blur">
+              <div className="absolute bottom-11 right-0 z-30 max-h-[70vh] min-w-44 overflow-y-auto rounded-xl border border-white/15 bg-black/85 p-1 shadow-2xl backdrop-blur">
                 <button
                   type="button"
                   onClick={() => {
@@ -481,10 +498,56 @@ export function PlayerControls({
                     }`}
                     title={track.label || track.lang}
                   >
-                    <span className="truncate">{track.label || track.lang || `字幕 ${index + 1}`}</span>
+                    <span className="truncate">
+                      {track.label || track.lang || `字幕 ${index + 1}`}
+                      {track.delivery === 'ass' ? ' · ASS' : ''}
+                    </span>
                     {subtitleIndex === index && <span className="ml-auto text-rose-400">●</span>}
                   </button>
                 ))}
+                {canAdjustSelectedSubtitle && (
+                  <div className="mt-1 border-t border-white/10 pt-1">
+                    <p className="px-3 py-1 text-[10px] text-white/45">字幕位置</p>
+                    <div className="flex flex-wrap gap-1 px-2 pb-1">
+                      {SUBTITLE_POSITION_OPTIONS.map(([value, label]) => (
+                        <button
+                          key={value}
+                          type="button"
+                          onClick={() => onSubtitlePositionChange(value)}
+                          className={`rounded-md px-2 py-1 text-[10px] transition ${
+                            subtitlePosition === value
+                              ? 'bg-rose-500/20 text-rose-300'
+                              : 'bg-white/5 text-white/70 hover:bg-white/10'
+                          }`}
+                        >
+                          {label}
+                        </button>
+                      ))}
+                    </div>
+                    <p className="px-3 py-1 text-[10px] text-white/45">字幕样式</p>
+                    <div className="flex flex-wrap gap-1 px-2 pb-1">
+                      {SUBTITLE_STYLE_OPTIONS.map(([value, label]) => (
+                        <button
+                          key={value}
+                          type="button"
+                          onClick={() => onSubtitleStyleChange(value)}
+                          className={`rounded-md px-2 py-1 text-[10px] transition ${
+                            subtitleStyle === value
+                              ? 'bg-rose-500/20 text-rose-300'
+                              : 'bg-white/5 text-white/70 hover:bg-white/10'
+                          }`}
+                        >
+                          {label}
+                        </button>
+                      ))}
+                    </div>
+                  </div>
+                )}
+                {usesOriginalASS && (
+                  <p className="mx-2 mt-1 border-t border-white/10 px-1 pt-2 text-[10px] leading-relaxed text-white/45">
+                    ASS/SSA 使用字幕文件自带的样式与位置，不做统一覆盖。
+                  </p>
+                )}
                 {canConvertSelectedSubtitle && (
                   <div className="mt-1 border-t border-white/10 pt-1">
                     <p className="px-3 py-1 text-[10px] text-white/45">外挂字幕简繁转换</p>

web/src/pages/PlayerPage.tsx

@@ -18,6 +18,14 @@ import {
   normalizeSubtitleChineseMode,
   type SubtitleChineseMode,
 } from '../utils/subtitleChinese'
+import {
+  loadSubtitlePosition,
+  loadSubtitleStyle,
+  saveSubtitlePosition,
+  saveSubtitleStyle,
+  type SubtitlePosition,
+  type SubtitleStylePreset,
+} from '../utils/subtitleDisplay'
 import { pickPlayerMode, needsTranscodeForBrowser, isDirectStreamMedia, type PlayerMode } from './playerPageModel'
 import { classifyDirectPlayError } from './directPlayError'
 import { apiErrorMessage } from './StrmManagePage'
@@ -63,6 +71,8 @@ export function PlayerPage() {
     useState<SubtitleChineseMode>(() =>
       normalizeSubtitleChineseMode(authUser?.subtitle_chinese_mode),
     )
+  const [subtitlePosition, setSubtitlePosition] = useState<SubtitlePosition>(loadSubtitlePosition)
+  const [subtitleStyle, setSubtitleStyle] = useState<SubtitleStylePreset>(loadSubtitleStyle)
   const persistedSubtitleChineseModeRef = useRef(subtitleChineseMode)
   const subtitlePreferenceTouchedRef = useRef(false)
   const subtitlePreferenceSaveQueueRef = useRef<Promise<void>>(Promise.resolve())
@@ -878,6 +888,16 @@ export function PlayerPage() {
     fallbackTimerRef.current = setTimeout(fallbackDirectPlay, 1500)
   }, [clearFallbackTimer, directOnly, hlsUnavailable, mediaId, mode, setPlaybackMode])
 
+  const changeSubtitlePosition = useCallback((nextPosition: SubtitlePosition) => {
+    setSubtitlePosition(nextPosition)
+    saveSubtitlePosition(nextPosition)
+  }, [])
+
+  const changeSubtitleStyle = useCallback((nextStyle: SubtitleStylePreset) => {
+    setSubtitleStyle(nextStyle)
+    saveSubtitleStyle(nextStyle)
+  }, [])
+
   const danmakuAutoTitle =
     danmakuInfo?.animeTitle ||
     media?.original_name?.trim() ||
@@ -910,6 +930,10 @@ export function PlayerPage() {
         onSelectSubtitle={selectSubtitle}
         subtitleChineseMode={subtitleChineseMode}
         onSubtitleChineseModeChange={changeSubtitleChineseMode}
+        subtitlePosition={subtitlePosition}
+        onSubtitlePositionChange={changeSubtitlePosition}
+        subtitleStyle={subtitleStyle}
+        onSubtitleStyleChange={changeSubtitleStyle}
         videoRef={ref}
         onVideoError={handleVideoError}
         danmakuEnabled={danmakuEnabled}

web/src/pages/PlayerVideoStage.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import type { PointerEvent, ReactNode, RefObject } from 'react'
+import type { CSSProperties, PointerEvent, ReactNode, RefObject } from 'react'
 
 import { subtitlesAPI, type SubtitleTrack } from '../api/subtitles'
 import { type DanmakuAnime, type DanmakuLoadedInfo } from '../api/danmaku'
@@ -8,55 +8,126 @@ import {
   loadSubtitleChineseConverter,
   type SubtitleChineseMode,
 } from '../utils/subtitleChinese'
+import { AssSubtitleStage } from '../components/AssSubtitleStage'
 import { DanmakuStage } from '../components/DanmakuStage'
 import { PlayerControls } from '../components/PlayerControls'
+import {
+  subtitleTextStyle,
+  type SubtitlePosition,
+  type SubtitleStylePreset,
+} from '../utils/subtitleDisplay'
+import { parseWebVTTCues, type SubtitleCue } from '../utils/subtitleVTT'
 
-type SubtitleCue = {
-  startTime: number
-  endTime: number
+type SubtitleRenderGroup = {
+  key: string
   text: string
+  style: CSSProperties
 }
 
-function parseVTTTimestamp(value: string): number {
-  const parts = value.trim().replace(',', '.').split(':')
-  if (parts.length !== 2 && parts.length !== 3) return Number.NaN
-  const seconds = Number(parts.pop())
-  const minutes = Number(parts.pop())
-  const hours = parts.length > 0 ? Number(parts.pop()) : 0
-  if (![hours, minutes, seconds].every(Number.isFinite)) return Number.NaN
-  return hours * 3600 + minutes * 60 + seconds
+function uniqueSubtitleCues(cues: SubtitleCue[]): SubtitleCue[] {
+  const seen = new Set<string>()
+  const unique: SubtitleCue[] = []
+  for (const cue of cues) {
+    const key = `${cue.startTime}\u0000${cue.endTime}\u0000${JSON.stringify(cue.settings)}\u0000${cue.text}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    unique.push(cue)
+  }
+  // WebVTT can contain more than two simultaneous tracks after ASS conversion.
+  // Keep the last two visual blocks, matching the previous bilingual behavior.
+  return unique.slice(-2)
 }
 
-function parseWebVTTCues(body: string): SubtitleCue[] {
-  const blocks = body
-    .replace(/^\uFEFF/, '')
-    .replace(/\r\n?/g, '\n')
-    .split(/\n{2,}/)
-  const cues: SubtitleCue[] = []
+function parsePercent(value: string | undefined): number | null {
+  if (!value || !value.endsWith('%')) return null
+  const parsed = Number.parseFloat(value)
+  return Number.isFinite(parsed) ? Math.min(100, Math.max(0, parsed)) : null
+}
 
-  for (const block of blocks) {
-    const lines = block.split('\n')
-    const timingIndex = lines.findIndex((line) => line.includes('-->'))
-    if (timingIndex < 0) continue
+function cueLineBottom(value: string | undefined): number | null {
+  const percent = parsePercent(value)
+  if (percent !== null) return Math.min(92, Math.max(2, 100 - percent))
+  if (value === undefined) return null
+  const line = Number.parseFloat(value)
+  if (!Number.isFinite(line)) return null
+  if (line < 0) return Math.min(92, Math.max(2, 6 - Math.abs(line) * 2))
+  return Math.min(92, Math.max(2, 7 + line * 8))
+}
 
-    const [rawStart, rawEnd] = lines[timingIndex].split('-->', 2)
-    const startTime = parseVTTTimestamp(rawStart)
-    const endTime = parseVTTTimestamp(rawEnd.trim().split(/\s+/, 1)[0])
-    const text = lines.slice(timingIndex + 1).join('\n').trim()
-    if (Number.isFinite(startTime) && Number.isFinite(endTime) && endTime >= startTime && text) {
-      cues.push({ startTime, endTime, text })
-    }
+function cueTextAlign(cue: SubtitleCue): CSSProperties['textAlign'] {
+  const align = cue.settings.align
+  if (align === 'left' || align === 'start') return 'left'
+  if (align === 'right' || align === 'end') return 'right'
+  return 'center'
+}
+
+function cuePlacementStyle(cue: SubtitleCue, position: SubtitlePosition): CSSProperties {
+  const style: CSSProperties = {
+    maxWidth: `${Math.min(cue.settings.size ?? 92, 94)}%`,
+    textAlign: cueTextAlign(cue),
   }
 
-  return cues
+  if (cue.settings.vertical) {
+    style.writingMode = cue.settings.vertical === 'lr' ? 'vertical-lr' : 'vertical-rl'
+  }
+
+  if (position !== 'auto') {
+    style.left = '50%'
+    style.textAlign = 'center'
+    if (position === 'bottom') {
+      style.bottom = '5%'
+      style.transform = 'translateX(-50%)'
+    } else if (position === 'lower') {
+      style.bottom = '13%'
+      style.transform = 'translateX(-50%)'
+    } else if (position === 'middle') {
+      style.top = '50%'
+      style.transform = 'translate(-50%, -50%)'
+    } else {
+      style.top = '7%'
+      style.transform = 'translateX(-50%)'
+    }
+    return style
+  }
+
+  const explicitPosition = cue.settings.position
+  const align = cue.settings.align
+  if (explicitPosition !== undefined) {
+    if (align === 'end' || align === 'right') {
+      style.right = `${100 - explicitPosition}%`
+    } else {
+      style.left = `${explicitPosition}%`
+      if (align !== 'start' && align !== 'left') style.transform = 'translateX(-50%)'
+    }
+  } else {
+    style.left = '50%'
+    style.transform = 'translateX(-50%)'
+  }
+
+  const bottom = cueLineBottom(cue.settings.line)
+  if (bottom !== null) style.bottom = `${bottom}%`
+  else style.bottom = '7%'
+  return style
 }
 
-function uniqueSubtitleTexts(texts: string[]): string[] {
-  const unique = [...new Set(texts.map((text) => text.trim()).filter(Boolean))]
-  // ponytail: WebVTT cannot preserve ASS layers/positions. Keep at most two
-  // simultaneous blocks for bilingual subtitles; use libass if full ASS
-  // typesetting support is added later.
-  return unique.slice(-2)
+function buildSubtitleRenderGroups(
+  cues: SubtitleCue[],
+  position: SubtitlePosition,
+): SubtitleRenderGroup[] {
+  const groups = new Map<string, SubtitleRenderGroup>()
+  for (const cue of cues) {
+    const style = cuePlacementStyle(cue, position)
+    const key = JSON.stringify(style)
+    const existing = groups.get(key)
+    if (existing) {
+      if (!existing.text.split('\n').includes(cue.text)) {
+        existing.text += `\n${cue.text}`
+      }
+      continue
+    }
+    groups.set(key, { key, text: cue.text, style })
+  }
+  return [...groups.values()]
 }
 
 type PlayerVideoStageProps = {
@@ -70,6 +141,10 @@ type PlayerVideoStageProps = {
   onSelectSubtitle: (index: number) => void
   subtitleChineseMode: SubtitleChineseMode
   onSubtitleChineseModeChange: (mode: SubtitleChineseMode) => void
+  subtitlePosition: SubtitlePosition
+  onSubtitlePositionChange: (position: SubtitlePosition) => void
+  subtitleStyle: SubtitleStylePreset
+  onSubtitleStyleChange: (style: SubtitleStylePreset) => void
   videoRef: RefObject<HTMLVideoElement>
   onVideoError: () => void
   danmakuEnabled: boolean
@@ -110,6 +185,10 @@ export function PlayerVideoStage({
   onSelectSubtitle,
   subtitleChineseMode,
   onSubtitleChineseModeChange,
+  subtitlePosition,
+  onSubtitlePositionChange,
+  subtitleStyle,
+  onSubtitleStyleChange,
   videoRef,
   onVideoError,
   danmakuEnabled,
@@ -144,7 +223,7 @@ export function PlayerVideoStage({
   const [controlsVisible, setControlsVisible] = useState(true)
   const revealControlsOnlyRef = useRef(false)
   // 当前展示的字幕文本（由自定义字幕层渲染，100% 透明无黑框）
-  const [activeCueText, setActiveCueText] = useState<string>('')
+  const [activeCues, setActiveCues] = useState<SubtitleCue[]>([])
   const [subtitleChineseConverter, setSubtitleChineseConverter] =
     useState<(text: string) => string>(() => (text: string) => text)
   // 独立保存完整 WebVTT 时间轴。HLS seek 会替换媒体源，Chromium 此时可能清空
@@ -155,6 +234,14 @@ export function PlayerVideoStage({
   } | null>(null)
   // 直连 302 尚未完成时插入 <track> 会中断加载并误报播放失败；等 canplay 再挂。
   const [tracksArmed, setTracksArmed] = useState(false)
+  // libass/WASM is optional at runtime. If it fails, ASS tracks fall back to
+  // the server's WebVTT conversion so playback still has visible subtitles.
+  const [assFallbackPath, setAssFallbackPath] = useState<string | null>(null)
+  const activeSubtitleTrack = subtitleIndex >= 0 ? subs[subtitleIndex] : undefined
+
+  useEffect(() => {
+    setAssFallbackPath(null)
+  }, [media?.id, activeSubtitleTrack?.path, subs])
 
   useEffect(() => {
     const selectedTrack = subs[subtitleIndex]
@@ -201,7 +288,10 @@ export function PlayerVideoStage({
 
   useEffect(() => {
     const selectedTrack = subs[subtitleIndex]
-    if (!media || subtitleIndex < 0 || !selectedTrack || selectedTrack.delivery !== 'webvtt') {
+    const useWebVTT =
+      selectedTrack?.delivery === 'webvtt' ||
+      (selectedTrack?.delivery === 'ass' && assFallbackPath === selectedTrack.path)
+    if (!media || subtitleIndex < 0 || !selectedTrack || !useWebVTT) {
       setSubtitleTimeline(null)
       return
     }
@@ -227,7 +317,7 @@ export function PlayerVideoStage({
       })
 
     return () => controller.abort()
-  }, [media, subs, subtitleIndex])
+  }, [assFallbackPath, media, subs, subtitleIndex])
 
   // 监听舞台容器的真实尺寸（响应窗口大小调整和全屏切换）
   useEffect(() => {
@@ -303,21 +393,22 @@ export function PlayerVideoStage({
       subs.length === 0 ||
       subtitleIndex < 0 ||
       !selectedTrack ||
-      selectedTrack.delivery === 'burn'
+      (selectedTrack.delivery !== 'webvtt' &&
+        !(selectedTrack.delivery === 'ass' && assFallbackPath === selectedTrack.path))
     ) {
-      setActiveCueText('')
+      setActiveCues([])
       return
     }
 
     const updateCue = () => {
       const absoluteTime = video.currentTime + (streamOffset ?? 0)
       if (subtitleTimeline?.path === selectedTrack.path) {
-        const texts = uniqueSubtitleTexts(
-          subtitleTimeline.cues
-            .filter((cue) => absoluteTime >= cue.startTime && absoluteTime <= cue.endTime)
-            .map((cue) => cue.text),
-        )
-        setActiveCueText(subtitleChineseConverter(texts.join('\n')))
+        const cues = uniqueSubtitleCues(
+          subtitleTimeline.cues.filter(
+            (cue) => absoluteTime >= cue.startTime && absoluteTime <= cue.endTime,
+          ),
+        ).map((cue) => ({ ...cue, text: subtitleChineseConverter(cue.text) }))
+        setActiveCues(cues)
         return
       }
 
@@ -326,17 +417,19 @@ export function PlayerVideoStage({
       )
       const tt = selectedEl?.track
       if (!tt) {
-        setActiveCueText('')
+        setActiveCues([])
         return
       }
 
       // 优先从浏览器 activeCues 中取当前文本；若浏览器在 hidden 模式下延迟触发 cuechange，
       // 则从 tt.cues 中根据 video.currentTime 实时匹配当前字幕，确保初次加载无感立即可见。
-      const texts: string[] = []
+      const cues: SubtitleCue[] = []
       if ((!streamOffset || streamOffset <= 0.05) && tt.activeCues && tt.activeCues.length > 0) {
         for (let i = 0; i < tt.activeCues.length; i++) {
           const cue = tt.activeCues[i] as VTTCue
-          if (cue && cue.text) texts.push(cue.text)
+          if (cue && cue.text) {
+            cues.push({ startTime: cue.startTime, endTime: cue.endTime, text: cue.text, settings: {} })
+          }
         }
       } else if (tt.cues && tt.cues.length > 0) {
         for (let i = 0; i < tt.cues.length; i++) {
@@ -347,11 +440,16 @@ export function PlayerVideoStage({
             absoluteTime <= cue.endTime &&
             cue.text
           ) {
-            texts.push(cue.text)
+            cues.push({ startTime: cue.startTime, endTime: cue.endTime, text: cue.text, settings: {} })
           }
         }
       }
-      setActiveCueText(subtitleChineseConverter(uniqueSubtitleTexts(texts).join('\n')))
+      setActiveCues(
+        uniqueSubtitleCues(cues).map((cue) => ({
+          ...cue,
+          text: subtitleChineseConverter(cue.text),
+        })),
+      )
     }
 
     const apply = () => {
@@ -415,6 +513,7 @@ export function PlayerVideoStage({
     subtitleTimeline,
     tracksArmed,
     subtitleChineseConverter,
+    assFallbackPath,
   ])
 
   // 根据视频画面宽高比与舞台宽高比，确定视频在哪个轴向撑满 100%
@@ -423,6 +522,7 @@ export function PlayerVideoStage({
       ? videoRatio > stageRect.width / stageRect.height
       : true
 
+  const assTrack = subtitleIndex >= 0 ? subs[subtitleIndex] : undefined
   const wrapperStyle = videoRatio
     ? {
         aspectRatio: `${videoRatio}`,
@@ -459,8 +559,11 @@ export function PlayerVideoStage({
               onError={onVideoError}
             >
               {tracksArmed &&
-                subs.map((track, index) =>
-                  track.delivery === 'burn' ? null : (
+                subs.map((track, index) => {
+                  const renderAsFallback =
+                    track.delivery === 'ass' && assFallbackPath === track.path
+                  if (track.delivery !== 'webvtt' && !renderAsFallback) return null
+                  return (
                     <track
                       key={track.path}
                       data-subtitle-index={index}
@@ -469,8 +572,8 @@ export function PlayerVideoStage({
                       srcLang={track.lang}
                       label={track.label || track.lang}
                     />
-                  ),
-                )}
+                  )
+                })}
             </video>
             <DanmakuStage
               key={media.id}
@@ -486,19 +589,40 @@ export function PlayerVideoStage({
               onLoaded={onDanmakuLoaded}
               onCandidates={onDanmakuCandidates}
             />
-            {/* 自定义沉浸式字幕层：纯透明背景 + 柔和阴影，完全消除浏览器原生黑框 */}
-            {activeCueText ? (
-              <div className="pointer-events-none absolute inset-x-0 bottom-4 sm:bottom-6 md:bottom-8 z-10 flex justify-center text-center px-4">
-                <span
-                  className="inline-block max-w-[92%] whitespace-pre-line text-center font-sans font-medium text-white text-base sm:text-lg md:text-xl lg:text-2xl select-none"
-                  style={{
-                    textShadow:
-                      '0 1px 3px rgba(0, 0, 0, 0.95), 0 0 8px rgba(0, 0, 0, 0.85), 0 0 16px rgba(0, 0, 0, 0.65)',
-                    lineHeight: 1.35,
-                  }}
-                >
-                  {activeCueText}
-                </span>
+            {tracksArmed && media && assTrack && assFallbackPath !== assTrack.path ? (
+              <AssSubtitleStage
+                key={`${media.id}:${assTrack.path}`}
+                videoRef={videoRef}
+                source={subtitlesAPI.assUrl(media.id, assTrack.path)}
+                timeOffset={streamOffset}
+                chineseMode={assTrack.source === 'external' ? subtitleChineseMode : 'original'}
+                onError={(error) => {
+                  console.warn('libass subtitle rendering failed; falling back to WebVTT', error)
+                  setAssFallbackPath(assTrack.path)
+                }}
+              />
+            ) : null}
+            {/* SRT/VTT 自定义字幕层：按 cue 位置对齐，并支持用户样式覆盖。 */}
+            {activeCues.length > 0 ? (
+              <div className="pointer-events-none absolute inset-0 z-10">
+                {buildSubtitleRenderGroups(activeCues, subtitlePosition).map((group) => (
+                  <div
+                    key={group.key}
+                    className="absolute flex px-4"
+                    style={group.style}
+                  >
+                    <span
+                      className="inline-block whitespace-pre-line font-sans text-white select-none"
+                      style={{
+                        ...subtitleTextStyle(subtitleStyle),
+                        fontSize: 'clamp(16px, 2.1vw, 30px)',
+                        lineHeight: 1.35,
+                      }}
+                    >
+                      {group.text}
+                    </span>
+                  </div>
+                ))}
               </div>
             ) : null}
           </div>
@@ -511,6 +635,10 @@ export function PlayerVideoStage({
             onSelectSubtitle={onSelectSubtitle}
             subtitleChineseMode={subtitleChineseMode}
             onSubtitleChineseModeChange={onSubtitleChineseModeChange}
+            subtitlePosition={subtitlePosition}
+            onSubtitlePositionChange={onSubtitlePositionChange}
+            subtitleStyle={subtitleStyle}
+            onSubtitleStyleChange={onSubtitleStyleChange}
             danmakuOpen={danmakuOpen}
             danmakuEnabled={danmakuEnabled}
             onToggleDanmaku={onToggleDanmaku}

web/src/utils/groupSeries.ts

@@ -480,20 +480,31 @@ export function groupSeries(items: Media[] = []): SeriesCard[] {
       if (betterSeriesLinkMedia(m, g.linkMedia)) {
         g.linkMedia = m
       }
-      const currentArtwork = artworkScore(m)
-      const representativeArtwork = artworkScore(g.rep)
-      if (currentArtwork > representativeArtwork) {
+      if (betterSeriesRepresentative(m, g.rep)) {
         g.rep = m
-      } else if (currentArtwork === representativeArtwork) {
-        const cur = (m.season_num ?? 0) * 10000 + (m.episode_num ?? 0)
-        const rep = (g.rep.season_num ?? 0) * 10000 + (g.rep.episode_num ?? 0)
-        if (cur > 0 && (rep === 0 || cur < rep)) g.rep = m
       }
     }
   }
   return Array.from(groups.values())
 }
 
+function betterSeriesRepresentative(candidate: Media, current: Media): boolean {
+  // A theatrical feature can have local poster/background artwork that scores
+  // higher than the TV poster. Keep the TV row as the series-card identity so
+  // the movie cannot replace the whole series title and overview.
+  const candidateTheatrical = isTheatricalFeature(candidate)
+  const currentTheatrical = isTheatricalFeature(current)
+  if (candidateTheatrical !== currentTheatrical) return !candidateTheatrical
+
+  const candidateArtwork = artworkScore(candidate)
+  const currentArtwork = artworkScore(current)
+  if (candidateArtwork !== currentArtwork) return candidateArtwork > currentArtwork
+
+  const cur = (candidate.season_num ?? 0) * 10000 + (candidate.episode_num ?? 0)
+  const rep = (current.season_num ?? 0) * 10000 + (current.episode_num ?? 0)
+  return cur > 0 && (rep === 0 || cur < rep)
+}
+
 function repeatedSeriesExternalRawKey(media: Media): string {
   if (!isEpisodeLike(media) && !pathLooksEpisodic(media)) return ''
   let identity = ''

web/src/utils/subtitleASS.ts

@@ -0,0 +1,32 @@
+export type SubtitleChineseConverter = (text: string) => string
+
+function commaIndexAtField(line: string, fieldCount: number): number {
+  let index = -1
+  for (let field = 0; field < fieldCount; field += 1) {
+    index = line.indexOf(',', index + 1)
+    if (index < 0) return -1
+  }
+  return index
+}
+
+/**
+ * Convert only the Text column of ASS/SSA Dialogue lines. ASS styling tags,
+ * drawings, timing and positioning metadata are bytes-for-bytes preserved so
+ * the event can still be rendered by libass after a Chinese conversion.
+ */
+export function convertASSContent(
+  content: string,
+  convert: SubtitleChineseConverter,
+): string {
+  return content
+    .replace(/^\uFEFF/, '')
+    .split(/\r?\n/)
+    .map((line) => {
+      const lower = line.toLowerCase()
+      if (!lower.startsWith('dialogue:')) return line
+      const textIndex = commaIndexAtField(line, 9)
+      if (textIndex < 0) return line
+      return `${line.slice(0, textIndex + 1)}${convert(line.slice(textIndex + 1))}`
+    })
+    .join('\n')
+}

web/src/utils/subtitleDisplay.ts

@@ -0,0 +1,99 @@
+import type { CSSProperties } from 'react'
+
+export type SubtitlePosition = 'auto' | 'bottom' | 'lower' | 'middle' | 'top'
+export type SubtitleStylePreset = 'shadow' | 'outline' | 'box'
+
+export const SUBTITLE_POSITION_OPTIONS: Array<[SubtitlePosition, string]> = [
+  ['auto', '默认位置'],
+  ['bottom', '贴底'],
+  ['lower', '下方'],
+  ['middle', '居中'],
+  ['top', '顶部'],
+]
+
+export const SUBTITLE_STYLE_OPTIONS: Array<[SubtitleStylePreset, string]> = [
+  ['shadow', '柔和阴影'],
+  ['outline', '黑边描边'],
+  ['box', '半透明底衬'],
+]
+
+const POSITION_KEY = 'mebox.subtitle.position'
+const STYLE_KEY = 'mebox.subtitle.style'
+
+export function normalizeSubtitlePosition(value: unknown): SubtitlePosition {
+  return value === 'bottom' || value === 'lower' || value === 'middle' || value === 'top'
+    ? value
+    : 'auto'
+}
+
+export function normalizeSubtitleStyle(value: unknown): SubtitleStylePreset {
+  return value === 'outline' || value === 'box' ? value : 'shadow'
+}
+
+export function loadSubtitlePosition(): SubtitlePosition {
+  if (typeof window === 'undefined') return 'auto'
+  try {
+    return normalizeSubtitlePosition(window.localStorage.getItem(POSITION_KEY))
+  } catch {
+    return 'auto'
+  }
+}
+
+export function loadSubtitleStyle(): SubtitleStylePreset {
+  if (typeof window === 'undefined') return 'shadow'
+  try {
+    return normalizeSubtitleStyle(window.localStorage.getItem(STYLE_KEY))
+  } catch {
+    return 'shadow'
+  }
+}
+
+export function saveSubtitlePosition(position: SubtitlePosition): void {
+  try {
+    window.localStorage.setItem(POSITION_KEY, position)
+  } catch {
+    // localStorage may be unavailable in private mode; the player still works.
+  }
+}
+
+export function saveSubtitleStyle(style: SubtitleStylePreset): void {
+  try {
+    window.localStorage.setItem(STYLE_KEY, style)
+  } catch {
+    // localStorage may be unavailable in private mode; the player still works.
+  }
+}
+
+export function subtitleTextStyle(style: SubtitleStylePreset): CSSProperties {
+  if (style === 'outline') {
+    return {
+      fontWeight: 700,
+      textShadow: [
+        '-1.5px 0 #000',
+        '1.5px 0 #000',
+        '0 -1.5px #000',
+        '0 1.5px #000',
+        '-1px -1px #000',
+        '1px -1px #000',
+        '-1px 1px #000',
+        '1px 1px #000',
+      ].join(', '),
+    }
+  }
+  if (style === 'box') {
+    return {
+      fontWeight: 600,
+      background: 'rgba(0, 0, 0, 0.72)',
+      padding: '0.16em 0.5em',
+      borderRadius: '0.24em',
+      boxDecorationBreak: 'clone',
+      WebkitBoxDecorationBreak: 'clone',
+      textShadow: '0 1px 2px rgba(0, 0, 0, 0.85)',
+    }
+  }
+  return {
+    fontWeight: 500,
+    textShadow:
+      '0 1px 3px rgba(0, 0, 0, 0.95), 0 0 8px rgba(0, 0, 0, 0.85), 0 0 16px rgba(0, 0, 0, 0.65)',
+  }
+}

web/src/utils/subtitleVTT.ts

@@ -0,0 +1,94 @@
+export type SubtitleCueAlignment = 'start' | 'center' | 'end' | 'left' | 'right'
+export type SubtitleCueVertical = 'rl' | 'lr'
+export type SubtitleCuePositionAlignment = SubtitleCueAlignment | 'line-left' | 'line-right' | 'auto'
+
+export type SubtitleCueSettings = {
+  align?: SubtitleCueAlignment
+  line?: string
+  lineAlign?: SubtitleCueAlignment
+  position?: number
+  positionAlign?: SubtitleCuePositionAlignment
+  size?: number
+  vertical?: SubtitleCueVertical
+}
+
+export type SubtitleCue = {
+  startTime: number
+  endTime: number
+  text: string
+  settings: SubtitleCueSettings
+}
+
+function parseVTTTimestamp(value: string): number {
+  const parts = value.trim().replace(',', '.').split(':')
+  if (parts.length !== 2 && parts.length !== 3) return Number.NaN
+  const seconds = Number(parts.pop())
+  const minutes = Number(parts.pop())
+  const hours = parts.length > 0 ? Number(parts.pop()) : 0
+  if (![hours, minutes, seconds].every(Number.isFinite)) return Number.NaN
+  return hours * 3600 + minutes * 60 + seconds
+}
+
+function parseCueSettings(tokens: string[]): SubtitleCueSettings {
+  const settings: SubtitleCueSettings = {}
+  for (const token of tokens) {
+    const colon = token.indexOf(':')
+    if (colon <= 0) continue
+    const key = token.slice(0, colon).toLowerCase()
+    const value = token.slice(colon + 1)
+    if (key === 'align') {
+      if (['start', 'center', 'end', 'left', 'right'].includes(value)) {
+        settings.align = value as SubtitleCueAlignment
+      }
+    } else if (key === 'line') {
+      settings.line = value
+    } else if (key === 'linealign') {
+      if (['start', 'center', 'end'].includes(value)) {
+        settings.lineAlign = value as SubtitleCueAlignment
+      }
+    } else if (key === 'position') {
+      const position = Number.parseFloat(value)
+      if (Number.isFinite(position)) settings.position = Math.min(100, Math.max(0, position))
+    } else if (key === 'positionalign') {
+      if (['start', 'center', 'end', 'line-left', 'line-right', 'auto'].includes(value)) {
+        settings.positionAlign = value as SubtitleCuePositionAlignment
+      }
+    } else if (key === 'size') {
+      const size = Number.parseFloat(value)
+      if (Number.isFinite(size)) settings.size = Math.min(100, Math.max(0, size))
+    } else if (key === 'vertical') {
+      if (value === 'rl' || value === 'lr') settings.vertical = value
+    }
+  }
+  return settings
+}
+
+export function parseWebVTTCues(body: string): SubtitleCue[] {
+  const blocks = body
+    .replace(/^\uFEFF/, '')
+    .replace(/\r\n?/g, '\n')
+    .split(/\n{2,}/)
+  const cues: SubtitleCue[] = []
+
+  for (const block of blocks) {
+    const lines = block.split('\n')
+    const timingIndex = lines.findIndex((line) => line.includes('-->'))
+    if (timingIndex < 0) continue
+
+    const [rawStart, rawRest] = lines[timingIndex].split('-->', 2)
+    const rest = rawRest.trim().split(/\s+/)
+    const startTime = parseVTTTimestamp(rawStart)
+    const endTime = parseVTTTimestamp(rest[0] || '')
+    const text = lines.slice(timingIndex + 1).join('\n').trim()
+    if (Number.isFinite(startTime) && Number.isFinite(endTime) && endTime >= startTime && text) {
+      cues.push({
+        startTime,
+        endTime,
+        text,
+        settings: parseCueSettings(rest.slice(1)),
+      })
+    }
+  }
+
+  return cues
+}

web/vite.config.ts

@@ -21,6 +21,11 @@ export default defineConfig({
       },
     },
   },
+  worker: {
+    // JASSUB ships its libass worker as an ES module. Vite's default IIFE
+    // worker output cannot split that worker's own imports.
+    format: 'es',
+  },
   build: {
     outDir: 'dist',
     sourcemap: false,