优化，现有bug处理

internal/handler/emby_items_handlers.go

@@ -40,9 +40,28 @@ func parseEmbyItemsParams(c *gin.Context) service.ItemsParams {
 		SortOrder:        firstQueryValue(c, "SortOrder", "sortOrder", "sortorder"),
 		Limit:            limit,
 		StartIndex:       offset,
+		SeasonIndex:      parseEmbySeasonIndexQuery(c),
 	}
 }
 
+// parseEmbySeasonIndexQuery 读取客户端请求的季序号。
+//
+// Emby 客户端有两种表达方式：SeasonId（虚拟季 ID）与 Season / SeasonIndex
+// （季序号，特别篇为 0）。两者都是合法入参，SeasonId 更精确。这里只解析季序号，
+// 返回 nil 表示客户端没有按季过滤（区别于 Season=0 的特别篇）。
+func parseEmbySeasonIndexQuery(c *gin.Context) *int {
+	raw := firstQueryValue(c, "Season", "season", "SeasonIndex", "seasonIndex", "seasonindex")
+	if raw == "" {
+		return nil
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		// 客户端偶尔传入季名称之类的非数字值；按「未过滤」处理，避免整季空结果。
+		return nil
+	}
+	return &value
+}
+
 func embyFirstNonEmptyString(values ...string) string {
 	for _, value := range values {
 		if strings.TrimSpace(value) != "" {
@@ -199,8 +218,15 @@ func embyShowSeasonsHandler(svc *service.Container) gin.HandlerFunc {
 func embyShowEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		parentID := firstQueryValue(c, "SeasonId", "seasonId")
+		// 客户端常用季序号而不是虚拟季 ID 请求剧集。缺了这层过滤，
+		// /Shows/{id}/Episodes?Season=2 会把整部剧的所有季都返回。
+		seasonIndex := parseEmbySeasonIndexQuery(c)
 		if parentID == "" {
 			parentID = c.Param("id")
+		} else {
+			// SeasonId 已经限定了具体季，忽略同时传来的季序号，避免两者
+			// 不一致时把结果过滤成空集。
+			seasonIndex = nil
 		}
 		params := service.ItemsParams{
 			UserID:           embyEffectiveUserID(c),
@@ -208,6 +234,7 @@ func embyShowEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 			IncludeItemTypes: []string{"Episode"},
 			Recursive:        true,
 			Limit:            500,
+			SeasonIndex:      seasonIndex,
 		}
 		out, err := svc.Emby.Items(c.Request.Context(), params)
 		if err != nil {

internal/handler/emby_show_episodes_season_test.go

@@ -0,0 +1,211 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// embySeasonEpisodesRouter builds an Emby-compatible router over one series with
+// two seasons, so /Shows/{id}/Episodes can be exercised with the query forms
+// real clients send.
+func embySeasonEpisodesRouter(t *testing.T) (*gin.Engine, string, string) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.User{}, &model.Library{}, &model.Series{}, &model.Media{}, &model.Favorite{}, &model.PlaybackHistory{}, &model.Setting{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		sqlDB.SetMaxOpenConns(1)
+	}
+	repos := repository.New(db)
+	if err := repos.User.Create(t.Context(), &model.User{
+		Base:         model.Base{ID: "user-1"},
+		Username:     "tester",
+		PasswordHash: "x",
+		Role:         "admin",
+		Tier:         "plus",
+		IsActive:     true,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	lib := model.Library{Name: "剧集", Path: "D:\\media\\tv", Type: "tv", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	for _, m := range []model.Media{
+		{
+			Base:       model.Base{ID: "s1e1"},
+			LibraryID:  lib.ID,
+			Title:      "Test Show",
+			Path:       "D:\\media\\tv\\Test Show\\Season 01\\Test Show - S01E01.mkv",
+			SeasonNum:  1,
+			EpisodeNum: 1,
+			Container:  "mkv",
+		},
+		{
+			Base:       model.Base{ID: "s2e1"},
+			LibraryID:  lib.ID,
+			Title:      "Test Show",
+			Path:       "D:\\media\\tv\\Test Show\\Season 02\\Test Show - S02E01.mkv",
+			SeasonNum:  2,
+			EpisodeNum: 1,
+			Container:  "mkv",
+		},
+	} {
+		if err := db.Create(&m).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	const secret = "test-secret"
+	router := gin.New()
+	registerEmbyRoutes(router, secret, &service.Container{
+		Repo: repos,
+		Emby: service.NewEmbyService(&config.Config{}, zap.NewNop(), repos),
+	})
+
+	// Resolve the virtual series id the way a client would.
+	seriesReq := httptest.NewRequest(http.MethodGet, "/Items?ParentId="+lib.ID+"&IncludeItemTypes=Series", nil)
+	seriesReq.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	seriesRec := httptest.NewRecorder()
+	router.ServeHTTP(seriesRec, seriesReq)
+	if seriesRec.Code != http.StatusOK {
+		t.Fatalf("series lookup status=%d body=%s", seriesRec.Code, seriesRec.Body.String())
+	}
+	var seriesPayload struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := json.Unmarshal(seriesRec.Body.Bytes(), &seriesPayload); err != nil {
+		t.Fatalf("decode series: %v", err)
+	}
+	if len(seriesPayload.Items) != 1 {
+		t.Fatalf("want one series, got %#v", seriesPayload.Items)
+	}
+	seriesID, _ := seriesPayload.Items[0]["Id"].(string)
+	if seriesID == "" {
+		t.Fatalf("series payload has no Id: %#v", seriesPayload.Items[0])
+	}
+	return router, secret, seriesID
+}
+
+func fetchEpisodeIDs(t *testing.T, router *gin.Engine, secret, path string) ([]string, int) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	req.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("%s status=%d body=%s", path, rec.Code, rec.Body.String())
+	}
+	var payload struct {
+		Items            []map[string]any `json:"Items"`
+		TotalRecordCount float64          `json:"TotalRecordCount"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode %s: %v", path, err)
+	}
+	ids := make([]string, 0, len(payload.Items))
+	for _, item := range payload.Items {
+		id, _ := item["Id"].(string)
+		ids = append(ids, id)
+	}
+	return ids, int(payload.TotalRecordCount)
+}
+
+// TestEmbyShowEpisodesHonoursSeasonQueryParam is the client-facing regression
+// test: Emby clients scope episodes with ?Season=<index> (not only SeasonId), and
+// the endpoint used to ignore it and return every season of the series.
+func TestEmbyShowEpisodesHonoursSeasonQueryParam(t *testing.T) {
+	router, secret, seriesID := embySeasonEpisodesRouter(t)
+
+	cases := []struct {
+		name    string
+		query   string
+		wantIDs []string
+	}{
+		{name: "season 1", query: "Season=1", wantIDs: []string{"s1e1"}},
+		{name: "season 2", query: "Season=2", wantIDs: []string{"s2e1"}},
+		{name: "season index alias", query: "SeasonIndex=2", wantIDs: []string{"s2e1"}},
+		{name: "no season returns all", query: "", wantIDs: []string{"s1e1", "s2e1"}},
+		{name: "unknown season is empty", query: "Season=9", wantIDs: []string{}},
+		{name: "non numeric season falls back to all", query: "Season=Specials", wantIDs: []string{"s1e1", "s2e1"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			path := "/Shows/" + seriesID + "/Episodes"
+			if tc.query != "" {
+				path += "?" + tc.query
+			}
+			ids, total := fetchEpisodeIDs(t, router, secret, path)
+			if len(ids) != len(tc.wantIDs) {
+				t.Fatalf("episode ids = %#v (total=%d), want %#v", ids, total, tc.wantIDs)
+			}
+			for i := range tc.wantIDs {
+				if ids[i] != tc.wantIDs[i] {
+					t.Fatalf("episode ids = %#v, want %#v", ids, tc.wantIDs)
+				}
+			}
+			if total != len(tc.wantIDs) {
+				t.Fatalf("TotalRecordCount = %d, want %d", total, len(tc.wantIDs))
+			}
+		})
+	}
+}
+
+// TestEmbyShowEpisodesSeasonIdStillWins pins that the virtual SeasonId form keeps
+// working, and that a conflicting Season query cannot empty it out.
+func TestEmbyShowEpisodesSeasonIdStillWins(t *testing.T) {
+	router, secret, seriesID := embySeasonEpisodesRouter(t)
+
+	seasonsPath := "/Shows/" + seriesID + "/Seasons"
+	req := httptest.NewRequest(http.MethodGet, seasonsPath, nil)
+	req.Header.Set("X-Emby-Token", signedTestToken(t, secret))
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("seasons status=%d body=%s", rec.Code, rec.Body.String())
+	}
+	var seasons struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &seasons); err != nil {
+		t.Fatalf("decode seasons: %v", err)
+	}
+	var season1ID string
+	for _, s := range seasons.Items {
+		if index, ok := s["IndexNumber"].(float64); ok && int(index) == 1 {
+			season1ID, _ = s["Id"].(string)
+		}
+	}
+	if season1ID == "" {
+		t.Fatalf("season 1 not found in %#v", seasons.Items)
+	}
+
+	ids, _ := fetchEpisodeIDs(t, router, secret, "/Shows/"+seriesID+"/Episodes?SeasonId="+season1ID)
+	if len(ids) != 1 || ids[0] != "s1e1" {
+		t.Fatalf("SeasonId episodes = %#v, want [s1e1]", ids)
+	}
+
+	// A stale/conflicting season number must not override the explicit season id.
+	ids, _ = fetchEpisodeIDs(t, router, secret, "/Shows/"+seriesID+"/Episodes?SeasonId="+season1ID+"&Season=2")
+	if len(ids) != 1 || ids[0] != "s1e1" {
+		t.Fatalf("SeasonId+Season episodes = %#v, want [s1e1]", ids)
+	}
+}

internal/service/cloud115_playback.go

@@ -58,12 +58,32 @@ type Cloud115PlaybackService struct {
 	repo *repository.Container
 	strm *StrmService
 
+	// transcoder 用于判断本地 HLS 档位此刻是否真的可用；未注入时按"不可用"处理，
+	// 避免向播放器推荐必然 500 的转码档位。
+	transcoder *TranscoderService
+
 	mu        sync.Mutex
 	pushState map[string]cloud115PushAttempt
 
 	proxy *Cloud115HLSProxy
 }
 
+// SetTranscoder 注入转码服务，用于标注本地 HLS 档位的可用性。
+func (s *Cloud115PlaybackService) SetTranscoder(transcoder *TranscoderService) *Cloud115PlaybackService {
+	if s != nil {
+		s.transcoder = transcoder
+	}
+	return s
+}
+
+// localTranscodeAvailable 报告本地 HLS 此刻是否可用。
+func (s *Cloud115PlaybackService) localTranscodeAvailable() bool {
+	if s == nil || s.transcoder == nil {
+		return false
+	}
+	return s.transcoder.Available()
+}
+
 func NewCloud115PlaybackService(cfg *config.Config, log *zap.Logger, repo *repository.Container, strm *StrmService) *Cloud115PlaybackService {
 	svc := &Cloud115PlaybackService{
 		cfg:       cfg,
@@ -101,7 +121,7 @@ func (s *Cloud115PlaybackService) PlaybackInfo(ctx context.Context, mediaID stri
 	}
 
 	provider := MediaPlaybackProvider(m)
-	localQualities := LocalQualityOptions(m)
+	localQualities := LocalQualityOptions(m, s.localTranscodeAvailable())
 	localDefault := DefaultLocalHLSQualityID(m)
 	info := &PlaybackInfo{
 		MediaID:        m.ID,

internal/service/emby_compat.go

@@ -141,6 +141,10 @@ type ItemsParams struct {
 	SortOrder        string
 	Limit            int
 	StartIndex       int
+	// SeasonIndex 对应客户端的 Season / SeasonIndex 查询参数（季序号，0 为特别篇）。
+	// nil 表示不按季过滤；非 nil 时只返回该季的剧集。客户端普遍用季序号而不是
+	// 虚拟季 ID 请求剧集，缺了它 /Shows/{id}/Episodes?Season=N 会返回整部剧。
+	SeasonIndex *int
 }
 
 const (

internal/service/emby_items_cache.go

@@ -47,10 +47,20 @@ func (e *EmbyService) embyItemsCacheKey(kind string, p ItemsParams) string {
 		p.SortOrder,
 		strconv.Itoa(p.StartIndex),
 		strconv.Itoa(p.Limit),
+		formatSeasonIndexCacheKeyPart(p.SeasonIndex),
 	}, "|")))
 	return "media:emby:" + hex.EncodeToString(sum[:])
 }
 
+// formatSeasonIndexCacheKeyPart keeps "no season filter" distinct from "season 0"
+// so a client's Season=0 (specials) request never reuses an unfiltered response.
+func formatSeasonIndexCacheKeyPart(seasonIndex *int) string {
+	if seasonIndex == nil {
+		return "season:*"
+	}
+	return "season:" + strconv.Itoa(*seasonIndex)
+}
+
 func (e *EmbyService) embyLatestCacheKey(userID, parentID string, limit int) string {
 	// v2: payload tags for virtual artwork changed so clients drop cached placeholders.
 	sum := sha256.Sum256([]byte(strings.Join([]string{"latest-v2", userID, parentID, strconv.Itoa(limit)}, "|")))

internal/service/emby_items_list.go

@@ -121,16 +121,31 @@ func (e *EmbyService) mediaItems(ctx context.Context, p ItemsParams) (map[string
 
 func (e *EmbyService) episodeItems(ctx context.Context, rows []model.Media, p ItemsParams) (map[string]any, error) {
 	rows = e.filterMediaRowsForUser(ctx, rows, p.UserID)
-	if p.SearchTerm != "" {
-		filtered := rows[:0]
-		needle := strings.ToLower(p.SearchTerm)
-		for _, row := range rows {
-			if strings.Contains(strings.ToLower(row.Title), needle) || strings.Contains(strings.ToLower(row.OriginalName), needle) {
-				filtered = append(filtered, row)
+	// rows 可能来自 series 分组的内存 memo（embySeriesGroup.Episodes）。过滤必须
+	// 分配新切片：就地复用 rows[:0] 会覆写 memo 里的元素，让后续请求看到被前一次
+	// 过滤污染的剧集列表（例如按季筛选一次之后，特别篇就从缓存分组里消失了）。
+	if p.SeasonIndex != nil {
+		filtered := make([]model.Media, 0, len(rows))
+		for i := range rows {
+			if embyRowMatchesSeasonIndex(&rows[i], p.SeasonIndex) {
+				filtered = append(filtered, rows[i])
 			}
 		}
 		rows = filtered
 	}
+	if p.SearchTerm != "" {
+		needle := strings.ToLower(p.SearchTerm)
+		filtered := make([]model.Media, 0, len(rows))
+		for i := range rows {
+			if strings.Contains(strings.ToLower(rows[i].Title), needle) || strings.Contains(strings.ToLower(rows[i].OriginalName), needle) {
+				filtered = append(filtered, rows[i])
+			}
+		}
+		rows = filtered
+	}
+	// sort.SliceStable 同样会就地重排：先拷贝一份，避免把 memo 分组里的剧集顺序
+	// 按每次请求的分页/筛选结果固定下来。
+	rows = append([]model.Media(nil), rows...)
 	sort.SliceStable(rows, func(i, j int) bool {
 		if rows[i].SeasonNum != rows[j].SeasonNum {
 			return rows[i].SeasonNum < rows[j].SeasonNum

internal/service/emby_season_index_test.go

@@ -0,0 +1,231 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// seasonIndexFixture builds one series covering every season-numbering class a
+// client can ask for: two regular seasons, a generic specials bucket (season 0)
+// and an OVA folder (negative season).
+func seasonIndexFixture(t *testing.T) (*EmbyService, string) {
+	t.Helper()
+	svc := newTestEmbyService(t)
+	lib := model.Library{Name: "剧集", Path: `F:\media\剧集`, Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	rows := []model.Media{
+		{
+			Base:       model.Base{ID: "s1e1"},
+			LibraryID:  lib.ID,
+			Title:      "權力的遊戲",
+			Path:       `F:\media\剧集\權力的遊戲 (2011)\Season 01\權力的遊戲 - S01E01.mkv`,
+			SeasonNum:  1,
+			EpisodeNum: 1,
+		},
+		{
+			Base:       model.Base{ID: "s1e2"},
+			LibraryID:  lib.ID,
+			Title:      "權力的遊戲",
+			Path:       `F:\media\剧集\權力的遊戲 (2011)\Season 01\權力的遊戲 - S01E02.mkv`,
+			SeasonNum:  1,
+			EpisodeNum: 2,
+		},
+		{
+			Base:       model.Base{ID: "s2e1"},
+			LibraryID:  lib.ID,
+			Title:      "權力的遊戲",
+			Path:       `F:\media\剧集\權力的遊戲 (2011)\Season 02\權力的遊戲 - S02E01.mkv`,
+			SeasonNum:  2,
+			EpisodeNum: 1,
+		},
+		{
+			Base:       model.Base{ID: "spec1"},
+			LibraryID:  lib.ID,
+			Title:      "權力的遊戲",
+			Path:       `F:\media\剧集\權力的遊戲 (2011)\Specials\權力的遊戲 - S00E01.mkv`,
+			SeasonNum:  0,
+			EpisodeNum: 1,
+		},
+		{
+			Base:       model.Base{ID: "ova1"},
+			LibraryID:  lib.ID,
+			Title:      "權力的遊戲",
+			Path:       `F:\media\剧集\權力的遊戲 (2011)\OVA\權力的遊戲 - OVA.mkv`,
+			SeasonNum:  0,
+			EpisodeNum: 1,
+		},
+	}
+	for i := range rows {
+		if err := svc.repo.DB.Create(&rows[i]).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	items, err := svc.Items(t.Context(), ItemsParams{
+		ParentID:         lib.ID,
+		IncludeItemTypes: []string{"Series"},
+		Limit:            10,
+	})
+	if err != nil {
+		t.Fatalf("series items: %v", err)
+	}
+	cards := items["Items"].([]map[string]any)
+	if len(cards) != 1 {
+		t.Fatalf("want one series card, got %#v", cards)
+	}
+	return svc, cards[0]["Id"].(string)
+}
+
+func episodeIDs(t *testing.T, out map[string]any) []string {
+	t.Helper()
+	items, ok := out["Items"].([]map[string]any)
+	if !ok {
+		t.Fatalf("Items has unexpected type: %#v", out["Items"])
+	}
+	ids := make([]string, 0, len(items))
+	for _, item := range items {
+		ids = append(ids, item["Id"].(string))
+	}
+	return ids
+}
+
+// itemsTotal reads TotalRecordCount, which is int on the episode path and int64
+// on the empty-envelope path.
+func itemsTotal(t *testing.T, out map[string]any) int {
+	t.Helper()
+	switch v := out["TotalRecordCount"].(type) {
+	case int:
+		return v
+	case int64:
+		return int(v)
+	default:
+		t.Fatalf("TotalRecordCount has unexpected type: %#v", out["TotalRecordCount"])
+		return 0
+	}
+}
+
+func assertEpisodeIDs(t *testing.T, got, want []string) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Fatalf("episode ids = %#v, want %#v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("episode ids = %#v, want %#v", got, want)
+		}
+	}
+}
+
+// TestEmbyEpisodeItemsFilterBySeasonIndex is the regression guard for clients
+// that scope episodes by season number (Season=N) instead of the virtual season
+// id: without the filter every season was returned for any requested season.
+func TestEmbyEpisodeItemsFilterBySeasonIndex(t *testing.T) {
+	svc, seriesID := seasonIndexFixture(t)
+
+	cases := []struct {
+		name      string
+		season    *int
+		wantIDs   []string
+		wantTotal int
+	}{
+		{
+			name:   "unfiltered returns every episode",
+			season: nil,
+			// episodeItems sorts by the stored season/episode numbers, so the two
+			// specials (both stored as season 0) come first in creation order.
+			wantIDs:   []string{"spec1", "ova1", "s1e1", "s1e2", "s2e1"},
+			wantTotal: 5,
+		},
+		{name: "season 1", season: intPtr(1), wantIDs: []string{"s1e1", "s1e2"}, wantTotal: 2},
+		{name: "season 2", season: intPtr(2), wantIDs: []string{"s2e1"}, wantTotal: 1},
+		{name: "season 0 is the specials bucket", season: intPtr(0), wantIDs: []string{"spec1"}, wantTotal: 1},
+		{name: "OVA season", season: intPtr(embySeasonOVA), wantIDs: []string{"ova1"}, wantTotal: 1},
+		{name: "unknown season is empty", season: intPtr(9), wantIDs: []string{}, wantTotal: 0},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			out, err := svc.Items(t.Context(), ItemsParams{
+				ParentID:         seriesID,
+				IncludeItemTypes: []string{"Episode"},
+				Recursive:        true,
+				Limit:            50,
+				SeasonIndex:      tc.season,
+			})
+			if err != nil {
+				t.Fatalf("items: %v", err)
+			}
+			assertEpisodeIDs(t, episodeIDs(t, out), tc.wantIDs)
+			if total := itemsTotal(t, out); total != tc.wantTotal {
+				t.Fatalf("TotalRecordCount = %d, want %d", total, tc.wantTotal)
+			}
+		})
+	}
+}
+
+// TestEmbySeasonIndexFilterKeepsSeasonIdsWorking pins the pre-existing
+// SeasonId behaviour: resolving through the virtual season id must still return
+// exactly that season.
+func TestEmbySeasonIndexFilterKeepsSeasonIdsWorking(t *testing.T) {
+	svc, seriesID := seasonIndexFixture(t)
+
+	items, err := svc.Items(t.Context(), ItemsParams{ParentID: seriesID, Limit: 50})
+	if err != nil {
+		t.Fatalf("seasons: %v", err)
+	}
+	seasons := items["Items"].([]map[string]any)
+	var seasonTwoID string
+	for _, season := range seasons {
+		if season["IndexNumber"] == 2 {
+			seasonTwoID = season["Id"].(string)
+		}
+	}
+	if seasonTwoID == "" {
+		t.Fatalf("season 2 missing from payload: %#v", seasons)
+	}
+
+	out, err := svc.Items(t.Context(), ItemsParams{
+		ParentID:         seasonTwoID,
+		IncludeItemTypes: []string{"Episode"},
+		Recursive:        true,
+		Limit:            50,
+	})
+	if err != nil {
+		t.Fatalf("season episodes: %v", err)
+	}
+	got := episodeIDs(t, out)
+	assertEpisodeIDs(t, got, []string{"s2e1"})
+}
+
+// TestEmbyItemsCacheKeySeparatesSeasonFilters guards against a cached unfiltered
+// response being reused for a season-scoped request (and vice versa).
+func TestEmbyItemsCacheKeySeparatesSeasonFilters(t *testing.T) {
+	svc := newTestEmbyService(t)
+	base := ItemsParams{ParentID: "series-1", IncludeItemTypes: []string{"Episode"}, Limit: 50}
+
+	unfiltered := svc.embyItemsCacheKey("items", base)
+	seasonZero := svc.embyItemsCacheKey("items", withSeasonIndex(base, 0))
+	seasonTwo := svc.embyItemsCacheKey("items", withSeasonIndex(base, 2))
+
+	if unfiltered == seasonZero {
+		t.Fatal("unfiltered and Season=0 keys must differ")
+	}
+	if unfiltered == seasonTwo {
+		t.Fatal("unfiltered and Season=2 keys must differ")
+	}
+	if seasonZero == seasonTwo {
+		t.Fatal("Season=0 and Season=2 keys must differ")
+	}
+	if again := svc.embyItemsCacheKey("items", withSeasonIndex(base, 2)); again != seasonTwo {
+		t.Fatal("cache key must be stable for the same season filter")
+	}
+}
+
+func withSeasonIndex(p ItemsParams, season int) ItemsParams {
+	p.SeasonIndex = intPtr(season)
+	return p
+}
+
+func intPtr(v int) *int { return &v }

internal/service/emby_series_ids.go

@@ -154,6 +154,16 @@ func embySeasonNumForMedia(m *model.Media) int {
 	return m.SeasonNum
 }
 
+// embyRowMatchesSeasonIndex 判断某条剧集是否属于客户端请求的季序号。
+// seasonIndex 为 nil 时不参与过滤。判定复用 embySeasonNumForMedia，保证与
+// /Shows/{id}/Seasons 暴露的 IndexNumber 完全一致（含特别篇的负数分类）。
+func embyRowMatchesSeasonIndex(m *model.Media, seasonIndex *int) bool {
+	if seasonIndex == nil {
+		return true
+	}
+	return embySeasonNumForMedia(m) == *seasonIndex
+}
+
 func embySeasonCandidates(seasonNum int) []int {
 	if seasonNum > 0 {
 		return []int{seasonNum}

internal/service/ffprobe.go

@@ -27,8 +27,19 @@ type FFprobeService struct {
 	log     *zap.Logger
 	mu      sync.RWMutex
 	limiter chan struct{}
+
+	// availMu guards the short-lived availability cache used by Available().
+	availMu        sync.Mutex
+	availCheckedAt time.Time
+	availValue     bool
 }
 
+// ffprobeAvailabilityTTL bounds how long an Available() result is reused.
+// Resolving a binary stats up to a couple dozen candidate paths, and the scanner
+// consults availability per root while deciding whether to queue backfill
+// probes. A short TTL keeps a freshly installed ffmpeg visible within seconds.
+const ffprobeAvailabilityTTL = 30 * time.Second
+
 // NewFFprobeService is the constructor.
 func NewFFprobeService(cfg *config.Config, log *zap.Logger) *FFprobeService {
 	maxConcurrent := normalizeFFprobeMaxConcurrent(cfg.App.FFprobeMaxConcurrent)
@@ -54,6 +65,29 @@ func (f *FFprobeService) SetMaxConcurrent(n int) {
 	f.limiter = make(chan struct{}, normalizeFFprobeMaxConcurrent(n))
 }
 
+// Available reports whether a probe can actually run right now: either an
+// ffprobe binary or the ffmpeg fallback must be resolvable. The scan path uses
+// this to decide whether re-queueing probes for media that still lack technical
+// metadata is worth doing — without a binary every probe would just fail.
+func (f *FFprobeService) Available() bool {
+	if f == nil || f.cfg == nil {
+		return false
+	}
+	f.availMu.Lock()
+	defer f.availMu.Unlock()
+	if !f.availCheckedAt.IsZero() && time.Since(f.availCheckedAt) < ffprobeAvailabilityTTL {
+		return f.availValue
+	}
+	available := true
+	if _, err := resolveLocalExecutable(f.cfg.App.FFprobePath, "ffprobe"); err != nil {
+		_, ffmpegErr := resolveLocalExecutable(f.cfg.App.FFmpegPath, "ffmpeg")
+		available = ffmpegErr == nil
+	}
+	f.availValue = available
+	f.availCheckedAt = time.Now()
+	return available
+}
+
 // ProbeResult is the subset of ffprobe output consumed by the scanner.
 type ProbeResult struct {
 	DurationSec int

internal/service/manual_scrape_test.go

@@ -199,7 +199,7 @@ func TestManualSearchFallsBackToMovieFolderForGenericQuery(t *testing.T) {
 			http.NotFound(w, r)
 			return
 		}
-		if r.URL.Query().Get("query") != "inception" {
+		if !strings.EqualFold(r.URL.Query().Get("query"), "inception") {
 			_ = json.NewEncoder(w).Encode(map[string]any{"results": []any{}})
 			return
 		}
@@ -248,7 +248,7 @@ func TestManualSearchFallsBackToMovieFolderForGenericQuery(t *testing.T) {
 	if len(results) != 1 || results[0].TMDbID != 27205 {
 		t.Fatalf("manual search results=%#v, want folder fallback candidate; queries=%v", results, queries)
 	}
-	if len(queries) < 2 || queries[0] != "00000" || queries[len(queries)-1] != "inception" {
+	if len(queries) < 2 || queries[0] != "00000" || !strings.EqualFold(queries[len(queries)-1], "inception") {
 		t.Fatalf("manual search queries=%v, want explicit query then folder fallback", queries)
 	}
 }

internal/service/nfo.go

@@ -76,7 +76,10 @@ type episodeNFO struct {
 }
 
 // ExportOne writes a movie.nfo file next to the media file. Existing files
-// are overwritten so a re-scrape always reflects the latest metadata.
+// are overwritten so a re-scrape always reflects the latest metadata. When the
+// folder already holds a sidecar the reader would pick (movie.nfo /
+// <dirname>.nfo), that file is updated in place instead of adding a second,
+// divergent NFO.
 func (s *NFOService) ExportOne(ctx context.Context, mediaID string) (string, error) {
 	m, err := s.repo.Media.FindByID(ctx, mediaID)
 	if err != nil {
@@ -191,12 +194,49 @@ func WriteMediaNFO(m *model.Media) (string, error) {
 		return "", err
 	}
 	dst := nfoPath(resolveMappedDestinationPath(m.Path))
+	if m.SeasonNum <= 0 && m.EpisodeNum <= 0 {
+		dst = nfoExportTarget(dst)
+	}
 	if err := os.WriteFile(dst, []byte(xml.Header+string(out)+"\n"), 0o644); err != nil { // #nosec G306 -- NFO sidecars must remain readable by media players.
 		return "", err
 	}
 	return dst, nil
 }
 
+// nfoExportTarget picks the file an export should write for a movie.
+//
+// Besides the canonical "<base>.nfo", the reader (findMovieNFO) also accepts
+// movie.nfo and "<dirname>.nfo". Writing the canonical name into a folder that
+// already carries one of those left two divergent NFOs for the same movie, and
+// because the reader prefers the canonical one the pre-existing file quietly went
+// stale. Reuse whichever file the reader would already have picked, in the same
+// precedence order, so an export updates the existing sidecar in place.
+//
+// Episodes are deliberately excluded by the caller: for an episode the
+// alternatives are series-level files, and writing episode metadata there would
+// corrupt the series identity.
+func nfoExportTarget(canonical string) string {
+	dir := filepath.Dir(canonical)
+	candidates := []string{
+		filepath.Base(canonical),
+		"movie.nfo",
+		filepath.Base(dir) + ".nfo",
+	}
+	for _, name := range candidates {
+		if name == "" || name == "." {
+			continue
+		}
+		candidate := filepath.Join(dir, name)
+		if candidate == canonical {
+			continue
+		}
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			return candidate
+		}
+	}
+	return canonical
+}
+
 func splitNFOList(value string) []string {
 	parts := strings.Split(value, ",")
 	out := make([]string, 0, len(parts))

internal/service/nfo_export_duplicate_test.go

@@ -0,0 +1,145 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func writeNFOTestFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A folder that already carries the Kodi/Emby convention "movie.nfo" must be
+// updated in place. Exporting used to always write "<filename>.nfo", leaving two
+// divergent NFOs for one movie — and since the reader prefers "<filename>.nfo",
+// the pre-existing movie.nfo silently went stale.
+func TestWriteMediaNFOUpdatesExistingMovieNFO(t *testing.T) {
+	dir := t.TempDir()
+	mediaPath := filepath.Join(dir, "The Shawshank Redemption (1994).mp4")
+	writeNFOTestFile(t, mediaPath, "video")
+	existing := filepath.Join(dir, "movie.nfo")
+	writeNFOTestFile(t, existing, `<?xml version="1.0"?><movie><title>旧标题</title></movie>`)
+
+	media := &model.Media{
+		Title:        "肖申克的救赎",
+		Year:         1994,
+		Path:         mediaPath,
+		Overview:     "希望让人自由。",
+		TMDbID:       278,
+		ScrapeStatus: "matched",
+	}
+	dst, err := WriteMediaNFO(media)
+	if err != nil {
+		t.Fatalf("WriteMediaNFO: %v", err)
+	}
+	if filepath.Clean(dst) != filepath.Clean(existing) {
+		t.Fatalf("export wrote %q, want the existing movie.nfo at %q", dst, existing)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "The Shawshank Redemption (1994).nfo")); err == nil {
+		t.Fatal("export created a duplicate <filename>.nfo next to movie.nfo")
+	}
+	body, err := os.ReadFile(existing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(body), "旧标题") || !strings.Contains(string(body), "肖申克的救赎") {
+		t.Fatalf("movie.nfo was not refreshed: %s", string(body))
+	}
+}
+
+// With no pre-existing sidecar the canonical <filename>.nfo is still the target.
+func TestWriteMediaNFOWritesCanonicalNameByDefault(t *testing.T) {
+	dir := t.TempDir()
+	mediaPath := filepath.Join(dir, "Inception (2010).mkv")
+	writeNFOTestFile(t, mediaPath, "video")
+
+	dst, err := WriteMediaNFO(&model.Media{Title: "盗梦空间", Year: 2010, Path: mediaPath})
+	if err != nil {
+		t.Fatalf("WriteMediaNFO: %v", err)
+	}
+	want := filepath.Join(dir, "Inception (2010).nfo")
+	if filepath.Clean(dst) != filepath.Clean(want) {
+		t.Fatalf("export wrote %q, want %q", dst, want)
+	}
+}
+
+// Re-exporting over an existing canonical sidecar must keep updating that file.
+func TestWriteMediaNFOOverwritesCanonicalSidecar(t *testing.T) {
+	dir := t.TempDir()
+	mediaPath := filepath.Join(dir, "Inception (2010).mkv")
+	writeNFOTestFile(t, mediaPath, "video")
+	canonical := filepath.Join(dir, "Inception (2010).nfo")
+	writeNFOTestFile(t, canonical, `<?xml version="1.0"?><movie><title>old</title></movie>`)
+
+	dst, err := WriteMediaNFO(&model.Media{Title: "盗梦空间", Year: 2010, Path: mediaPath})
+	if err != nil {
+		t.Fatalf("WriteMediaNFO: %v", err)
+	}
+	if filepath.Clean(dst) != filepath.Clean(canonical) {
+		t.Fatalf("export wrote %q, want %q", dst, canonical)
+	}
+	body, _ := os.ReadFile(canonical)
+	if strings.Contains(string(body), ">old<") {
+		t.Fatal("existing canonical sidecar was not refreshed")
+	}
+}
+
+// Episode exports must never be redirected to the series-level movie.nfo /
+// <dirname>.nfo files: those describe the show, not the episode.
+func TestWriteMediaNFOEpisodeIgnoresSeriesLevelSidecars(t *testing.T) {
+	dir := t.TempDir()
+	mediaPath := filepath.Join(dir, "Show - S01E01.mkv")
+	writeNFOTestFile(t, mediaPath, "video")
+	seriesNFO := filepath.Join(dir, "movie.nfo")
+	writeNFOTestFile(t, seriesNFO, `<?xml version="1.0"?><movie><title>series level</title></movie>`)
+
+	dst, err := WriteMediaNFO(&model.Media{
+		Title:      "Show",
+		Path:       mediaPath,
+		SeasonNum:  1,
+		EpisodeNum: 1,
+	})
+	if err != nil {
+		t.Fatalf("WriteMediaNFO: %v", err)
+	}
+	if filepath.Clean(dst) == filepath.Clean(seriesNFO) {
+		t.Fatal("episode export must not overwrite the series-level movie.nfo")
+	}
+	if filepath.Clean(dst) != filepath.Clean(filepath.Join(dir, "Show - S01E01.nfo")) {
+		t.Fatalf("episode export wrote %q, want the episode sidecar", dst)
+	}
+	body, _ := os.ReadFile(seriesNFO)
+	if !strings.Contains(string(body), "series level") {
+		t.Fatal("series-level movie.nfo was modified by an episode export")
+	}
+}
+
+// The <dirname>.nfo convention must be reused too.
+func TestWriteMediaNFOUpdatesDirectoryNamedNFO(t *testing.T) {
+	parent := t.TempDir()
+	dir := filepath.Join(parent, "Interstellar (2014)")
+	mediaPath := filepath.Join(dir, "Interstellar (2014).mkv")
+	writeNFOTestFile(t, mediaPath, "video")
+	dirNFO := filepath.Join(dir, "Interstellar (2014).nfo")
+	// The directory-named sidecar is the only pre-existing candidate besides the
+	// canonical name, so the canonical name is skipped and this one is reused.
+	writeNFOTestFile(t, dirNFO, `<?xml version="1.0"?><movie><title>old</title></movie>`)
+
+	dst, err := WriteMediaNFO(&model.Media{Title: "星际穿越", Year: 2014, Path: mediaPath})
+	if err != nil {
+		t.Fatalf("WriteMediaNFO: %v", err)
+	}
+	if filepath.Clean(dst) != filepath.Clean(dirNFO) {
+		t.Fatalf("export wrote %q, want %q", dst, dirNFO)
+	}
+}

internal/service/organizer_reclassify_metadata_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"go.uber.org/zap"
@@ -24,7 +25,10 @@ func TestOrganizeDirectoryCleansReleaseNoiseBeforeMetadataClassify(t *testing.T)
 		}
 		query := r.URL.Query().Get("query")
 		queries = append(queries, query)
-		if query != "motherhood of taihang" {
+		// Real providers match the query case-insensitively; keep this stub
+		// faithful so the test guards release-noise cleaning rather than the
+		// historical lowercased query spelling.
+		if !strings.EqualFold(query, "motherhood of taihang") {
 			_ = json.NewEncoder(w).Encode(map[string]any{"results": []any{}})
 			return
 		}
@@ -81,7 +85,7 @@ func TestOrganizeDirectoryCleansReleaseNoiseBeforeMetadataClassify(t *testing.T)
 	if _, err := os.Stat(want); err != nil {
 		t.Fatalf("organized media missing at %q: %v; items=%#v queries=%v", want, err, res.Items, queries)
 	}
-	if len(queries) == 0 || queries[0] != "motherhood of taihang" {
+	if len(queries) == 0 || !strings.EqualFold(queries[0], "motherhood of taihang") {
 		t.Fatalf("first metadata query = %q, want cleaned title; all queries=%v", firstQuery(queries), queries)
 	}
 }

internal/service/organizer_scrape_providers_test.go

@@ -74,7 +74,9 @@ func TestOrganizeDirectoryUsesAdultMetadataBeforeRename(t *testing.T) {
 
 func TestOrganizeDirectoryUsesBangumiForAnimeRename(t *testing.T) {
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/search/subject/frieren" {
+		// Bangumi takes the keyword in the path; compare case-insensitively so the
+		// stub does not pin the query spelling (titles now keep their original case).
+		if !strings.EqualFold(r.URL.Path, "/search/subject/frieren") {
 			http.NotFound(w, r)
 			return
 		}

internal/service/playback_quality.go

@@ -211,13 +211,25 @@ func DefaultCloud115Quality(options []PlaybackQuality) string {
 }
 
 // LocalQualityOptions 返回 MeBox 本地 HLS 可用的画质档位。
-func LocalQualityOptions(m *model.Media) []PlaybackQuality {
+//
+// transcodeAvailable 为 false（未装 ffmpeg、或转码被全局关闭）时档位仍然返回，
+// 但 Available 为 false：播放器据此直接走直连播放，而不是先请求 /api/hls 拿到
+// 一个必然失败的 500 再回退。档位列表保留是为了让前端仍能展示"需要转码"的说明。
+func LocalQualityOptions(m *model.Media, transcodeAvailable bool) []PlaybackQuality {
 	sourceHeight := mediaSourceHeight(m)
 	presets := []PlaybackQuality{
-		{ID: "source", Label: "原画", Height: sourceHeight, Source: "local", Available: true, Note: "本地 HLS，保持源分辨率"},
-		{ID: "1080", Label: "1080P", Height: 1080, Source: "local", Available: true},
-		{ID: "720", Label: "720P", Height: 720, Source: "local", Available: true},
-		{ID: "480", Label: "480P", Height: 480, Source: "local", Available: true},
+		{ID: "source", Label: "原画", Height: sourceHeight, Source: "local", Available: transcodeAvailable, Note: "本地 HLS，保持源分辨率"},
+		{ID: "1080", Label: "1080P", Height: 1080, Source: "local", Available: transcodeAvailable},
+		{ID: "720", Label: "720P", Height: 720, Source: "local", Available: transcodeAvailable},
+		{ID: "480", Label: "480P", Height: 480, Source: "local", Available: transcodeAvailable},
+	}
+	if !transcodeAvailable {
+		for i := range presets {
+			presets[i].RequiresTranscode = true
+			if presets[i].Note == "" {
+				presets[i].Note = "需要 ffmpeg，当前不可用"
+			}
+		}
 	}
 	out := make([]PlaybackQuality, 0, len(presets))
 	for _, preset := range presets {

internal/service/playback_quality_test.go

@@ -61,20 +61,45 @@ func TestCloud115QualityOptionsListsAvailableOnlyOnce(t *testing.T) {
 
 func TestLocalQualityOptionsFollowSourceHeight(t *testing.T) {
 	media := &model.Media{Height: 720}
-	options := LocalQualityOptions(media)
+	options := LocalQualityOptions(media, true)
 	if _, ok := findPlaybackQuality(options, "1080"); ok {
 		t.Fatal("720p source should not list 1080P")
 	}
 	for _, id := range []string{"source", "720", "480"} {
-		if _, ok := findPlaybackQuality(options, id); !ok {
+		quality, ok := findPlaybackQuality(options, id)
+		if !ok {
 			t.Fatalf("local quality %s missing", id)
 		}
+		if !quality.Available {
+			t.Fatalf("local quality %s should be available while transcoding works", id)
+		}
 	}
 	if got := DefaultLocalHLSQualityID(media); got != "720" {
 		t.Fatalf("default local quality = %q, want 720", got)
 	}
 }
 
+// Without a usable ffmpeg the local HLS renditions must not advertise themselves
+// as available: the player would request /api/hls/... and take a guaranteed 500
+// before falling back to direct play.
+func TestLocalQualityOptionsMarkUnavailableWithoutTranscoder(t *testing.T) {
+	media := &model.Media{Height: 1080}
+	for _, id := range []string{"source", "1080", "720", "480"} {
+		for _, available := range []bool{true, false} {
+			quality, ok := findPlaybackQuality(LocalQualityOptions(media, available), id)
+			if !ok {
+				t.Fatalf("local quality %s missing", id)
+			}
+			if quality.Available != available {
+				t.Fatalf("quality %s availability = %v, want %v", id, quality.Available, available)
+			}
+			if !available && !quality.RequiresTranscode {
+				t.Fatalf("unavailable quality %s should be flagged as requiring transcoding", id)
+			}
+		}
+	}
+}
+
 func TestLocalHLSQualityFFmpegArgs(t *testing.T) {
 	cfg := &config.Config{}
 	cfg.Transcoder.MaxHeight = 720

internal/service/recognition_words_test.go

@@ -20,8 +20,8 @@ One\.Piece\.S01E(89[2-9]|9\d{2}|10\d{2})\.1999 => 海贼王.S21E\1.1999 && S21E
 
 func TestCleanQueryWithRecognitionDisabledByDefaultRepoNil(t *testing.T) {
 	title, year := CleanQueryWithRecognition(t.Context(), nil, "Dune.2021.2160p.WEB-DL.mkv")
-	if title != "dune" || year != 2021 {
-		t.Fatalf("CleanQueryWithRecognition = %q/%d, want dune/2021", title, year)
+	if title != "Dune" || year != 2021 {
+		t.Fatalf("CleanQueryWithRecognition = %q/%d, want Dune/2021", title, year)
 	}
 }
 

internal/service/runtime_cache.go

@@ -36,6 +36,16 @@ type RuntimeCacheService struct {
 	limit     int
 	maxBytes  int64
 	bytesUsed int64
+	// seq stamps every insert/access with a strictly increasing number. Two
+	// entries written or touched inside the same clock tick carry an identical
+	// lastUsed, and Go map iteration order is random, so eviction used to pick an
+	// arbitrary "oldest" entry. seq turns recency into a total order.
+	seq uint64
+}
+
+func (c *RuntimeCacheService) nextSeqLocked() uint64 {
+	c.seq++
+	return c.seq
 }
 
 type runtimeCacheItem struct {
@@ -43,6 +53,7 @@ type runtimeCacheItem struct {
 	expiresAt  time.Time
 	staleUntil time.Time
 	lastUsed   time.Time
+	seq        uint64
 	size       int64
 }
 
@@ -55,6 +66,7 @@ type runtimeObjectItem struct {
 	value     any
 	expiresAt time.Time
 	lastUsed  time.Time
+	seq       uint64
 	size      int64
 }
 
@@ -225,6 +237,7 @@ func (c *RuntimeCacheService) GetObject(key string) (any, bool) {
 		return nil, false
 	}
 	item.lastUsed = now
+	item.seq = c.nextSeqLocked()
 	c.obj[fullKey] = item
 	c.mu.Unlock()
 	return item.value, true
@@ -252,6 +265,7 @@ func (c *RuntimeCacheService) SetObject(key string, value any, ttl time.Duration
 		value:     value,
 		expiresAt: now.Add(ttl),
 		lastUsed:  now,
+		seq:       c.nextSeqLocked(),
 		size:      size,
 	}
 	c.bytesUsed += size
@@ -334,6 +348,7 @@ func (c *RuntimeCacheService) getMemoryWithStale(key string) ([]byte, bool, bool
 		return nil, false, false
 	}
 	item.lastUsed = now
+	item.seq = c.nextSeqLocked()
 	c.memory[key] = item
 	return item.raw, true, !now.Before(item.expiresAt)
 }
@@ -376,6 +391,7 @@ func (c *RuntimeCacheService) setMemoryBytesWithStale(key string, raw []byte, fr
 		expiresAt:  now.Add(freshTTL),
 		staleUntil: now.Add(staleTTL),
 		lastUsed:   now,
+		seq:        c.nextSeqLocked(),
 		size:       size,
 	}
 	c.bytesUsed += size
@@ -424,20 +440,36 @@ func (c *RuntimeCacheService) evictExpiredLocked(now time.Time) {
 	}
 }
 
+// evictOldestLocked removes the least recently used entry across both caches.
+//
+// Recency is ordered by (lastUsed, seq): entries written within the same clock
+// tick share lastUsed, and map iteration order is randomized, so comparing
+// timestamps alone let eviction drop a just-written entry instead of the older
+// one. seq breaks those ties deterministically.
 func (c *RuntimeCacheService) evictOldestLocked() bool {
 	var (
 		oldestKey  string
 		oldestKind byte
 		oldestAt   time.Time
+		oldestSeq  uint64
 	)
+	older := func(at time.Time, seq uint64) bool {
+		if oldestKind == 0 {
+			return true
+		}
+		if at.Equal(oldestAt) {
+			return seq < oldestSeq
+		}
+		return at.Before(oldestAt)
+	}
 	for key, item := range c.memory {
-		if oldestKind == 0 || item.lastUsed.Before(oldestAt) {
-			oldestKey, oldestKind, oldestAt = key, 'm', item.lastUsed
+		if older(item.lastUsed, item.seq) {
+			oldestKey, oldestKind, oldestAt, oldestSeq = key, 'm', item.lastUsed, item.seq
 		}
 	}
 	for key, item := range c.obj {
-		if oldestKind == 0 || item.lastUsed.Before(oldestAt) {
-			oldestKey, oldestKind, oldestAt = key, 'o', item.lastUsed
+		if older(item.lastUsed, item.seq) {
+			oldestKey, oldestKind, oldestAt, oldestSeq = key, 'o', item.lastUsed, item.seq
 		}
 	}
 	switch oldestKind {

internal/service/runtime_cache_eviction_test.go

@@ -0,0 +1,108 @@
+package service
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Eviction must be deterministic when entries share a lastUsed timestamp.
+//
+// Regression: recency was compared by lastUsed alone. Entries written within the
+// same clock tick carry identical timestamps and Go map iteration order is
+// randomized, so eviction could drop a just-written entry instead of the oldest
+// one — which made TestRuntimeCacheSetMaxSizeEvictsImmediately fail intermittently
+// in a full-package run.
+func TestRuntimeCacheEvictionBreaksTimestampTiesDeterministically(t *testing.T) {
+	// Repeat because the bug only showed up for some map iteration orders.
+	for attempt := 0; attempt < 50; attempt++ {
+		cache := newRuntimeCacheForTest(t, 128)
+		const perEntry = 700 << 10
+
+		// Two entries large enough that a 1MiB budget can hold only one. Writing
+		// them back to back puts them in the same clock tick often enough to hit
+		// the tie almost immediately.
+		cache.SetObject("old", strings.Repeat("a", perEntry), time.Minute)
+		cache.SetObject("new", strings.Repeat("b", perEntry), time.Minute)
+
+		cache.SetMaxSizeMB(1)
+
+		if _, ok := cache.GetObject("old"); ok {
+			t.Fatalf("attempt %d: oldest entry survived the budget drop", attempt)
+		}
+		if _, ok := cache.GetObject("new"); !ok {
+			t.Fatalf("attempt %d: newest entry was evicted instead of the oldest", attempt)
+		}
+	}
+}
+
+// Accessing an entry refreshes its recency even when it lands in the same tick as
+// the write of a competing entry.
+func TestRuntimeCacheAccessRefreshesEvictionOrder(t *testing.T) {
+	cache := newRuntimeCacheForTest(t, 128)
+	const perEntry = 700 << 10
+
+	cache.SetObject("first", strings.Repeat("a", perEntry), time.Minute)
+	cache.SetObject("second", strings.Repeat("b", perEntry), time.Minute)
+	// Touch the older entry so it becomes the more recent one.
+	if _, ok := cache.GetObject("first"); !ok {
+		t.Fatal("first entry should be present before the budget drop")
+	}
+
+	cache.SetMaxSizeMB(1)
+
+	if _, ok := cache.GetObject("second"); ok {
+		t.Fatal("the untouched entry should have been evicted first")
+	}
+	if _, ok := cache.GetObject("first"); !ok {
+		t.Fatal("the just-accessed entry should have been kept")
+	}
+}
+
+// Eviction picks the oldest across the byte cache and the object cache together.
+func TestRuntimeCacheEvictionComparesBothCaches(t *testing.T) {
+	cache := newRuntimeCacheForTest(t, 128)
+	const perEntry = 700 << 10
+
+	// Byte-cache entry written first, object-cache entry second.
+	payload := strings.Repeat("c", perEntry)
+	cache.SetJSON(context.Background(), "bytes", payload, time.Minute)
+	cache.SetObject("object", strings.Repeat("d", perEntry), time.Minute)
+
+	cache.SetMaxSizeMB(1)
+
+	if _, ok := cache.GetObject("object"); !ok {
+		t.Fatal("the newer object entry must be kept")
+	}
+	var decoded string
+	if cache.GetJSON(context.Background(), "bytes", &decoded) {
+		t.Fatal("the older byte-cache entry should have been evicted")
+	}
+}
+
+// The sequence counter must hand out strictly increasing values, otherwise ties
+// would resolve randomly again.
+func TestRuntimeCacheSequenceIsMonotonic(t *testing.T) {
+	cache := newRuntimeCacheForTest(t, 16)
+	seen := map[uint64]bool{}
+	cache.mu.Lock()
+	var previous uint64
+	for i := 0; i < 100; i++ {
+		seq := cache.nextSeqLocked()
+		if seen[seq] {
+			cache.mu.Unlock()
+			t.Fatalf("sequence %d handed out twice", seq)
+		}
+		if seq <= previous && previous != 0 {
+			cache.mu.Unlock()
+			t.Fatalf("sequence went backwards: %d after %d", seq, previous)
+		}
+		seen[seq] = true
+		previous = seq
+	}
+	cache.mu.Unlock()
+	if len(seen) != 100 {
+		t.Fatalf("expected 100 distinct sequence numbers, got %d", len(seen))
+	}
+}

internal/service/sanitize_dotdir_test.go

@@ -0,0 +1,79 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+// Dot-prefixed directory names are legal and common (hidden media folders,
+// ".staging" drop dirs). cleanEntryName used to trim dots from BOTH ends, which
+// silently rewrote `.media` into `media`.
+func TestCleanEntryNameKeepsLeadingDots(t *testing.T) {
+	cases := []struct {
+		name  string
+		isDir bool
+		want  string
+	}{
+		{name: ".media", isDir: true, want: ".media"},
+		{name: ".tmp-live-media", isDir: true, want: ".tmp-live-media"},
+		{name: ".staging", isDir: true, want: ".staging"},
+		{name: "Season 01.", isDir: true, want: "Season 01"},
+		{name: "  trailing space  ", isDir: true, want: "trailing space"},
+		{name: ".hidden.mkv", isDir: false, want: ".hidden.mkv"},
+		{name: "poster.jpg", isDir: false, want: "poster.jpg"},
+		{name: "file:name?test*<foo>|bar\".mkv", isDir: false, want: "file nametestfoobar.mkv"},
+		// Names that are nothing but dots must still collapse to a safe placeholder.
+		{name: ".", isDir: true, want: "unnamed"},
+		{name: "..", isDir: true, want: "unnamed"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := cleanEntryName(tc.name, tc.isDir); got != tc.want {
+				t.Fatalf("cleanEntryName(%q, %v) = %q, want %q", tc.name, tc.isDir, got, tc.want)
+			}
+		})
+	}
+}
+
+// sanitizeLocalPath must preserve a dot-prefixed directory in the middle of an
+// absolute path. Regression: artwork sidecars for a library at
+// `<root>/.tmp-live-media/电影/...` were written to `<root>/tmp-live-media/...`
+// instead — a sibling tree outside the media folder.
+func TestSanitizeLocalPathKeepsDotPrefixedSegments(t *testing.T) {
+	dir := filepath.Join(string(filepath.Separator)+"media", ".hidden-lib", "电影", "Inception (2010)")
+	got := sanitizeLocalPath(dir)
+	if got != dir {
+		t.Fatalf("sanitizeLocalPath(%q) = %q, want the path unchanged", dir, got)
+	}
+}
+
+// End-to-end guard for the observed bug: writing scraped artwork into a media
+// folder located under a dot-prefixed library root must land inside that folder,
+// never in a dot-stripped sibling directory.
+func TestArtworkWriteKeepsDotPrefixedLibraryPath(t *testing.T) {
+	root := t.TempDir()
+	libraryRoot := filepath.Join(root, ".media")
+	mediaDir := filepath.Join(libraryRoot, "电影", "Inception (2010)")
+	if err := os.MkdirAll(mediaDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	svc := &ScraperService{log: zap.NewNop()}
+	dst := svc.writeArtworkDataToPath(mediaDir, "Inception (2010)-poster", "image/jpeg", []byte{0xff, 0xd8, 0xff, 0xdb, 0x00})
+	if dst == "" {
+		t.Fatal("artwork write reported no destination")
+	}
+	if filepath.Dir(filepath.Clean(dst)) != filepath.Clean(mediaDir) {
+		t.Fatalf("artwork written to %q, want a file inside %q", dst, mediaDir)
+	}
+	if _, err := os.Stat(filepath.Join(mediaDir, "Inception (2010)-poster.jpg")); err != nil {
+		t.Fatalf("sidecar missing from the media folder: %v", err)
+	}
+	// A dot-stripped sibling must not be created.
+	if _, err := os.Stat(filepath.Join(root, "media")); err == nil {
+		t.Fatal("dot-stripped sibling directory was created")
+	}
+}

internal/service/scanner_incremental_test.go

@@ -114,11 +114,11 @@ func TestScanLibraryUsesISOParentFolderForScrapeIdentity(t *testing.T) {
 	if err := repos.DB.First(&media).Error; err != nil {
 		t.Fatal(err)
 	}
-	if media.Title != "dune part two" || media.Year != 2024 || media.ScrapeStatus != "pending" {
+	if media.Title != "Dune Part Two" || media.Year != 2024 || media.ScrapeStatus != "pending" {
 		t.Fatalf("ISO scrape identity = title=%q year=%d status=%q", media.Title, media.Year, media.ScrapeStatus)
 	}
 	candidates := scrapeQueryCandidates(&media, &lib)
-	if len(candidates) == 0 || candidates[0] != "dune part two" {
+	if len(candidates) == 0 || candidates[0] != "Dune Part Two" {
 		t.Fatalf("ISO scrape candidates = %#v", candidates)
 	}
 }
@@ -161,7 +161,7 @@ func TestScanLibraryRepairsPreviouslyUnmatchedGenericISO(t *testing.T) {
 	if err := repos.DB.First(&media, "id = ?", legacy.ID).Error; err != nil {
 		t.Fatal(err)
 	}
-	if media.Title != "dune part two" || media.Year != 2024 || media.ScrapeStatus != "pending" {
+	if media.Title != "Dune Part Two" || media.Year != 2024 || media.ScrapeStatus != "pending" {
 		t.Fatalf("repaired ISO = title=%q year=%d status=%q", media.Title, media.Year, media.ScrapeStatus)
 	}
 }

internal/service/scanner_local_ingest.go

@@ -122,11 +122,52 @@ func (s *ScannerService) localMediaScanState(in localMediaScanStateInput) (bool,
 	existing, exists := in.existingMedia[in.cleanPath]
 	isNewMedia := !exists
 	if exists && in.ext != ".strm" && existing.SizeBytes == in.size && !localMetadataNeedsRefresh(existing, in.localMeta) && !localDerivedMetadataNeedsRefresh(existing, in.incoming) {
+		// Unchanged rows are skipped, but a row that never received ffprobe data
+		// still needs a backfill probe so installing ffmpeg later repairs the library.
+		s.queueProbeBackfillIfNeeded(in.path, in.ext, existing)
 		return isNewMedia, true
 	}
 	return isNewMedia, false
 }
 
+// queueProbeBackfillIfNeeded re-queues ffprobe for an unchanged media row that
+// still carries no technical metadata, reporting whether a probe was queued.
+//
+// The incremental skip above only compares file size and metadata, so a library
+// scanned while ffprobe was unavailable kept duration/resolution/codec empty
+// forever: installing ffmpeg and rescanning did nothing, and the only way out was
+// a per-item manual "探测媒体轨". Only the probe is re-queued here — the row
+// itself is not rewritten, so scraped metadata and titles stay untouched.
+func (s *ScannerService) queueProbeBackfillIfNeeded(path, ext string, existing existingLocalMedia) bool {
+	if !mediaExtensionSupportsProbe(ext) || !localMediaProbeDataMissing(existing) {
+		return false
+	}
+	// Without a resolvable ffprobe/ffmpeg every queued probe would just fail, so
+	// only queue when probing is actually possible right now.
+	if s == nil || s.probe == nil || !s.probe.Available() {
+		return false
+	}
+	if !s.queueLocalMediaProbe(path) {
+		return false
+	}
+	if s.log != nil {
+		s.log.Debug("rescan queued ffprobe backfill for media without track metadata", zap.String("path", path))
+	}
+	return true
+}
+
+// localMediaProbeDataMissing reports whether a media row has none of the fields
+// ffprobe fills in. Requiring every field to be empty keeps genuinely probed
+// media (which always yields at least a codec or a duration) out of the backfill
+// path.
+func localMediaProbeDataMissing(existing existingLocalMedia) bool {
+	return existing.DurationSec <= 0 &&
+		existing.Width <= 0 &&
+		existing.Height <= 0 &&
+		strings.TrimSpace(existing.VideoCodec) == "" &&
+		strings.TrimSpace(existing.AudioCodec) == ""
+}
+
 type localScanMediaInput struct {
 	lib           *model.Library
 	root          *model.LibraryRoot

internal/service/scanner_local_metadata_test.go

@@ -263,7 +263,7 @@ func TestScanLibraryRefreshesStaleNoMatchDerivedMetadata(t *testing.T) {
 	if err := db.First(&media, "path = ?", mediaPath).Error; err != nil {
 		t.Fatal(err)
 	}
-	if media.Title != "hntv spring festival gala" || media.SeasonNum != 1 || media.EpisodeNum != 202 || media.ScrapeStatus != "pending" {
+	if media.Title != "Hntv Spring Festival Gala" || media.SeasonNum != 1 || media.EpisodeNum != 202 || media.ScrapeStatus != "pending" {
 		t.Fatalf("stale no_match row was not refreshed: title=%q s=%d e=%d status=%q", media.Title, media.SeasonNum, media.EpisodeNum, media.ScrapeStatus)
 	}
 }

internal/service/scanner_probe_backfill_test.go

@@ -0,0 +1,167 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// newProbeBackfillScanner builds a scanner over the given repository whose
+// ffprobe "binary" is a temp file, so probe availability is deterministic
+// regardless of what happens to be installed on the test machine.
+func newProbeBackfillScanner(t *testing.T, repos *repository.Container, probeAvailable bool) *ScannerService {
+	t.Helper()
+	cfg := &config.Config{}
+	probePath := filepath.Join(t.TempDir(), "not-a-real-ffprobe")
+	if probeAvailable {
+		if err := os.WriteFile(probePath, []byte("stub"), 0o755); err != nil {
+			t.Fatalf("write stub probe: %v", err)
+		}
+	}
+	// Point the probe and its ffmpeg fallback at paths that only exist when this
+	// test wants them to, so Available() cannot pick up a system binary.
+	cfg.App.FFprobePath = probePath
+	cfg.App.FFmpegPath = probePath
+	return NewScannerService(cfg, zap.NewNop(), repos, NewHub(zap.NewNop()), NewFFprobeService(cfg, zap.NewNop()), nil)
+}
+
+func newProbeBackfillRepo(t *testing.T) *repository.Container {
+	t.Helper()
+	return repository.New(newServiceTestDB(t, &model.Library{}, &model.Media{}, &model.Setting{}))
+}
+
+func probeBackfillScanner(t *testing.T, probeAvailable bool) *ScannerService {
+	t.Helper()
+	return newProbeBackfillScanner(t, newProbeBackfillRepo(t), probeAvailable)
+}
+
+// localMediaProbeDataMissing decides which unchanged rows are worth re-probing.
+func TestLocalMediaProbeDataMissing(t *testing.T) {
+	cases := []struct {
+		name     string
+		existing existingLocalMedia
+		want     bool
+	}{
+		{name: "never probed", existing: existingLocalMedia{}, want: true},
+		{name: "duration only", existing: existingLocalMedia{DurationSec: 148}, want: false},
+		{name: "resolution only", existing: existingLocalMedia{Width: 1920, Height: 1080}, want: false},
+		{name: "video codec only", existing: existingLocalMedia{VideoCodec: "h264"}, want: false},
+		{name: "audio codec only", existing: existingLocalMedia{AudioCodec: "aac"}, want: false},
+		{name: "fully probed", existing: existingLocalMedia{DurationSec: 148, Width: 1920, Height: 1080, VideoCodec: "h264", AudioCodec: "aac"}, want: false},
+		{name: "blank codecs are not data", existing: existingLocalMedia{VideoCodec: "  ", AudioCodec: " "}, want: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := localMediaProbeDataMissing(tc.existing); got != tc.want {
+				t.Fatalf("localMediaProbeDataMissing(%+v) = %v, want %v", tc.existing, got, tc.want)
+			}
+		})
+	}
+}
+
+// A rescan must re-queue ffprobe for media that still has no technical metadata,
+// otherwise a library scanned before ffmpeg was installed stays empty forever.
+func TestRescanQueuesProbeBackfillForUnprobedMedia(t *testing.T) {
+	sc := probeBackfillScanner(t, true)
+
+	if !sc.queueProbeBackfillIfNeeded("/media/movie.mkv", ".mkv", existingLocalMedia{}) {
+		t.Fatal("unprobed media should get a backfill probe queued")
+	}
+	if sc.queueProbeBackfillIfNeeded("/media/movie.mkv", ".mkv", existingLocalMedia{DurationSec: 148, VideoCodec: "h264"}) {
+		t.Fatal("already probed media must not be re-queued")
+	}
+}
+
+// Backfill is pointless without a usable binary: every probe would fail, so the
+// scanner must not flood the probe queue.
+func TestRescanSkipsProbeBackfillWhenProbeUnavailable(t *testing.T) {
+	sc := probeBackfillScanner(t, false)
+
+	if sc.probe.Available() {
+		t.Skip("a system ffprobe/ffmpeg is resolvable in this environment; availability gating cannot be exercised")
+	}
+	if sc.queueProbeBackfillIfNeeded("/media/movie.mkv", ".mkv", existingLocalMedia{}) {
+		t.Fatal("no probe should be queued while ffprobe/ffmpeg is unavailable")
+	}
+}
+
+// Formats that mediaExtensionSupportsProbe excludes must never enter the backfill
+// path, even when the row looks unprobed.
+func TestRescanSkipsProbeBackfillForUnprobeableExtensions(t *testing.T) {
+	sc := probeBackfillScanner(t, true)
+
+	for _, ext := range []string{".strm", ".iso"} {
+		if sc.queueProbeBackfillIfNeeded("/media/item"+ext, ext, existingLocalMedia{}) {
+			t.Fatalf("ext %s must not be queued for a probe backfill", ext)
+		}
+	}
+}
+
+// End-to-end guard: after a scan leaves a row without technical metadata, the
+// incremental-skip path for an unchanged file must still schedule a backfill
+// probe rather than skipping the file forever.
+func TestScanLibraryQueuesBackfillOnUnchangedRescan(t *testing.T) {
+	repos := newProbeBackfillRepo(t)
+	root := t.TempDir()
+	lib := model.Library{Name: "Movies", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(root, "Some Movie (2021).mkv")
+	if err := os.WriteFile(file, []byte("data"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	first := newProbeBackfillScanner(t, repos, true)
+	res, err := first.ScanLibrary(t.Context(), lib.ID)
+	if err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+	if res.Added != 1 {
+		t.Fatalf("first scan added=%d, want 1", res.Added)
+	}
+
+	var existing existingLocalMedia
+	if err := repos.DB.Model(&model.Media{}).
+		Select("duration_sec", "width", "height", "video_codec", "audio_codec", "size_bytes").
+		Where("path = ?", file).Scan(&existing).Error; err != nil {
+		t.Fatal(err)
+	}
+	if !localMediaProbeDataMissing(existing) {
+		t.Fatalf("fixture precondition failed, media already has probe data: %+v", existing)
+	}
+
+	// A fresh scanner instance has no probe in flight for this path, which is what
+	// a later rescan (e.g. after the operator installs ffmpeg) looks like.
+	second := newProbeBackfillScanner(t, repos, true)
+	_, skipUnchanged := second.localMediaScanState(localMediaScanStateInput{
+		ctx:           t.Context(),
+		path:          file,
+		cleanPath:     filepath.Clean(file),
+		ext:           ".mkv",
+		size:          existing.SizeBytes,
+		existingMedia: map[string]existingLocalMedia{filepath.Clean(file): existing},
+	})
+	if !skipUnchanged {
+		t.Fatal("unchanged file should take the incremental-skip path")
+	}
+
+	// Control: a different unprobed path on the same instance still queues, so the
+	// instance is demonstrably able to schedule probes.
+	other := filepath.Join(root, "Another Movie (2022).mkv")
+	if !second.queueProbeBackfillIfNeeded(other, ".mkv", existing) {
+		t.Fatal("control path should queue a backfill probe")
+	}
+	// Therefore the incremental-skip path above must already have queued this path:
+	// queueing reserves the path, so a second attempt is refused. If the skip path
+	// had not queued it, this call would have succeeded.
+	if second.queueProbeBackfillIfNeeded(file, ".mkv", existing) {
+		t.Fatal("unchanged unprobed media was not queued by the incremental-skip path")
+	}
+}

internal/service/scraper_query_case_test.go

@@ -0,0 +1,68 @@
+package service
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestCleanQueryPreservesOriginalTitleCase is the regression guard for English
+// titles being lowercased on ingest: "The.Matrix.1999.1080p.BluRay.x264-AMIABLE"
+// used to be stored as "the matrix", which also made metadata providers miss it.
+func TestCleanQueryPreservesOriginalTitleCase(t *testing.T) {
+	cases := []struct {
+		in        string
+		wantTitle string
+		wantYear  int
+	}{
+		{"The.Matrix.1999.1080p.BluRay.x264-AMIABLE.mkv", "The Matrix", 1999},
+		{"The.Shawshank.Redemption.1994.1080p.BluRay.mkv", "The Shawshank Redemption", 1994},
+		{"Interstellar.2014.2160p.WEB-DL.mkv", "Interstellar", 2014},
+		{"Breaking.Bad.S01E01.1080p.WEB-DL.mkv", "Breaking Bad", 0},
+		{"Fast.and.Furious.2001.mkv", "Fast and Furious", 2001},
+		{"spider-man.2002.1080p.mkv", "spider man", 2002},
+	}
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			gotTitle, gotYear := CleanQuery(tc.in)
+			if gotTitle != tc.wantTitle || gotYear != tc.wantYear {
+				t.Errorf("CleanQuery(%q) = (%q, %d), want (%q, %d)",
+					tc.in, gotTitle, gotYear, tc.wantTitle, tc.wantYear)
+			}
+		})
+	}
+}
+
+// The release-tag rules run on lowercased tokens, so restoring the display case
+// must not change which tokens survive. Anything that starts matching or
+// dropping tokens only because of casing (e.g. patEP's boundary class seeing an
+// uppercase letter) would show up here.
+func TestCleanQueryCaseRestoreDoesNotChangeTokenSelection(t *testing.T) {
+	// Both spellings must select exactly the same title tokens.
+	pairs := [][2]string{
+		{"The.Matrix.1999.1080p.BluRay.mkv", "the.matrix.1999.1080p.bluray.mkv"},
+		{"SE7EN.1995.1080p.BluRay.mkv", "se7en.1995.1080p.bluray.mkv"},
+		{"WEB.Therapy.S01E01.1080p.mkv", "web.therapy.s01e01.1080p.mkv"},
+		{"For.All.Mankind.S05E06.4K.mkv", "for.all.mankind.s05e06.4k.mkv"},
+	}
+	for _, pair := range pairs {
+		upper, upperYear := CleanQuery(pair[0])
+		lower, lowerYear := CleanQuery(pair[1])
+		if !equalFoldASCII(upper, lower) || upperYear != lowerYear {
+			t.Errorf("case changed token selection: %q -> (%q, %d) vs %q -> (%q, %d)",
+				pair[0], upper, upperYear, pair[1], lower, lowerYear)
+		}
+	}
+}
+
+func equalFoldASCII(a, b string) bool {
+	return strings.EqualFold(a, b)
+}
+
+// A filename with no case information (all lowercase, as many release names are)
+// must stay as-is rather than being title-cased: MeBox cannot invent casing.
+func TestCleanQueryKeepsLowercaseInputLowercase(t *testing.T) {
+	title, _ := CleanQuery("the.matrix.1999.1080p.mkv")
+	if title != "the matrix" {
+		t.Fatalf("CleanQuery = %q, want %q", title, "the matrix")
+	}
+}

internal/service/scraper_query_clean.go

@@ -172,10 +172,53 @@ func CleanQuery(raw string) (title string, year int) {
 		}
 		out = append(out, w)
 	}
-	title = strings.TrimSpace(strings.Join(out, " "))
+	title = strings.TrimSpace(strings.Join(restoreQueryTokenCase(name, out), " "))
 	return title, year
 }
 
+// queryTokenSeparators mirrors the separator split used while tokenising a
+// cleaned filename.
+var queryTokenSeparators = []string{".", "_", "-", "[", "]", "(", ")", "×"}
+
+// restoreQueryTokenCase maps the surviving lowercase tokens of a cleaned
+// filename back onto the spelling used in the original name.
+//
+// Tokenisation itself stays case-insensitive: the release-tag rules in this file
+// rely on lowercased tokens (and patEP's [^a-z] boundary would misfire on
+// "SE7EN"-style names if it ran on mixed case). Rebuilding the display title from
+// the original tokens afterwards keeps "The.Matrix.1999.1080p..." as "The Matrix"
+// instead of overwriting the user's media with a lowercased title — the lowercased
+// form also used to poison metadata lookups. Tokens with no original counterpart
+// (fragments produced by a removal) fall back to their lowercase form.
+func restoreQueryTokenCase(name string, tokens []string) []string {
+	if len(tokens) == 0 {
+		return tokens
+	}
+	originalByLower := make(map[string]string, len(tokens))
+	normalized := bracketedTag.ReplaceAllString(name, " ")
+	for _, sep := range queryTokenSeparators {
+		normalized = strings.ReplaceAll(normalized, sep, " ")
+	}
+	for _, token := range strings.Fields(normalized) {
+		key := strings.ToLower(token)
+		if key == "" || key == releaseSignalToken {
+			continue
+		}
+		if _, exists := originalByLower[key]; !exists {
+			originalByLower[key] = token
+		}
+	}
+	cased := make([]string, 0, len(tokens))
+	for _, token := range tokens {
+		if original, ok := originalByLower[token]; ok {
+			cased = append(cased, original)
+			continue
+		}
+		cased = append(cased, token)
+	}
+	return cased
+}
+
 func isASCIIWord(s string) bool {
 	if s == "" {
 		return false

internal/service/scraper_query_clean_regression_test.go

@@ -12,10 +12,10 @@ func TestCleanQueryKeepsCommonEnglishTitleWords(t *testing.T) {
 		wantTitle string
 		wantYear  int
 	}{
-		{"Mad.Max.1979.1080p.BluRay.mkv", "mad max", 1979},
-		{"Max.Payne.2008.1080p.WEB-DL.mkv", "max payne", 2008},
-		{"Web.Therapy.S01E01.1080p.WEB-DL.mkv", "web therapy", 0},
-		{"The.Web.2019.1080p.mkv", "the web", 2019},
+		{"Mad.Max.1979.1080p.BluRay.mkv", "Mad Max", 1979},
+		{"Max.Payne.2008.1080p.WEB-DL.mkv", "Max Payne", 2008},
+		{"Web.Therapy.S01E01.1080p.WEB-DL.mkv", "Web Therapy", 0},
+		{"The.Web.2019.1080p.mkv", "The Web", 2019},
 	}
 	for _, tc := range cases {
 		t.Run(tc.in, func(t *testing.T) {
@@ -43,8 +43,8 @@ func TestCleanQueryDoesNotTruncateAmbiguousTagToNothing(t *testing.T) {
 // truncation but must not discard the real title words that follow it.
 func TestCleanQueryKeepsTitleAfterYearPrefix(t *testing.T) {
 	cases := map[string]string{
-		"2019.Avatar.1080p.BluRay.mkv":     "avatar",
-		"2024.Dune.Part.Two.2160p.WEB.mkv": "dune part two",
+		"2019.Avatar.1080p.BluRay.mkv":     "Avatar",
+		"2024.Dune.Part.Two.2160p.WEB.mkv": "Dune Part Two",
 	}
 	for in, want := range cases {
 		t.Run(in, func(t *testing.T) {
@@ -62,9 +62,9 @@ func TestCleanQueryKeepsTitleAfterYearPrefix(t *testing.T) {
 func TestCleanQueryStillDropsTagsAfterReleaseSignal(t *testing.T) {
 	cases := map[string]string{
 		"复仇者联盟4.2019.BD.1080p.mkv":               "复仇者联盟4",
-		"The.Matrix.1999.1080p.WEB-DL.H265.mp4":  "the matrix",
-		"Oppenheimer.2023.2160p.UHD.BluRay.mkv":  "oppenheimer",
-		"Interstellar.2014.4k.hdr.dts.atmos.mkv": "interstellar",
+		"The.Matrix.1999.1080p.WEB-DL.H265.mp4":  "The Matrix",
+		"Oppenheimer.2023.2160p.UHD.BluRay.mkv":  "Oppenheimer",
+		"Interstellar.2014.4k.hdr.dts.atmos.mkv": "Interstellar",
 	}
 	for in, want := range cases {
 		t.Run(in, func(t *testing.T) {

internal/service/scraper_query_movie_test.go

@@ -30,7 +30,7 @@ func TestScrapeQueryCandidatesUseMovieFolderForGenericFilename(t *testing.T) {
 	if len(got) == 0 {
 		t.Fatal("scrapeQueryCandidates returned no candidates")
 	}
-	if got[0] != "inception" {
+	if got[0] != "Inception" {
 		t.Fatalf("first query candidate = %q, want movie folder title; all candidates=%#v", got[0], got)
 	}
 	for _, candidate := range got {
@@ -55,7 +55,7 @@ func TestScrapeQueryCandidatesUseMovieLibraryRootWhenMountedAtMovieFolder(t *tes
 	if len(got) == 0 {
 		t.Fatal("scrapeQueryCandidates returned no candidates")
 	}
-	if got[0] != "inception" {
+	if got[0] != "Inception" {
 		t.Fatalf("first query candidate = %q, want movie library root title; all candidates=%#v", got[0], got)
 	}
 }
@@ -73,7 +73,7 @@ func TestScrapeQueryCandidatesDoNotUseMovieCollectionFolderAsTitle(t *testing.T)
 	if len(got) == 0 {
 		t.Fatal("scrapeQueryCandidates returned no candidates")
 	}
-	if got[0] != "the hunger games catching fire" {
+	if got[0] != "The Hunger Games Catching Fire" {
 		t.Fatalf("first query candidate = %q, want individual movie title; all candidates=%#v", got[0], got)
 	}
 	for _, candidate := range got {
@@ -92,7 +92,10 @@ func TestEnrichOneUsesMovieFolderWhenFilenameIsGeneric(t *testing.T) {
 			http.NotFound(w, r)
 			return
 		}
-		if r.URL.Query().Get("query") != "inception" {
+		// Real metadata providers treat the query case-insensitively; this stub
+		// must too, otherwise it would only be pinned to the historical lowercased
+		// query spelling instead of the folder-fallback behaviour it guards.
+		if !strings.EqualFold(r.URL.Query().Get("query"), "inception") {
 			_ = json.NewEncoder(w).Encode(map[string]any{"results": []any{}})
 			return
 		}
@@ -149,7 +152,7 @@ func TestEnrichOneUsesMovieFolderWhenFilenameIsGeneric(t *testing.T) {
 	if got.ScrapeStatus != "matched" || got.TMDbID != 27205 || got.Title != "Inception" {
 		t.Fatalf("generic filename scrape did not use folder title: status=%q tmdb=%d title=%q queries=%v", got.ScrapeStatus, got.TMDbID, got.Title, queries)
 	}
-	if len(queries) == 0 || queries[0] != "inception" {
+	if len(queries) == 0 || !strings.EqualFold(queries[0], "inception") {
 		t.Fatalf("first tmdb query = %q, want folder title; all queries=%v", firstQuery(queries), queries)
 	}
 }

internal/service/scraper_query_test.go

@@ -23,19 +23,19 @@ func TestCleanQuery(t *testing.T) {
 		wantTitle string
 		wantYear  int
 	}{
-		{"Inception.2010.1080p.BluRay.x264.mkv", "inception", 2010},
-		{"The_Matrix_(1999).1080p.WEB-DL.H265.mp4", "the matrix", 1999},
+		{"Inception.2010.1080p.BluRay.x264.mkv", "Inception", 2010},
+		{"The_Matrix_(1999).1080p.WEB-DL.H265.mp4", "The Matrix", 1999},
 		{"interstellar.2014.4k.hdr.dts.atmos.mkv", "interstellar", 2014},
-		{"My Movie 2022 [HDR] (1080p) [TGx].mp4", "my movie", 2022},
-		{"NoYearOrTags.mkv", "noyearortags", 0},
-		{"亏成首富从游戏开始 The Richest in Game - S01E11 - 4K.mp4", "亏成首富从游戏开始 the richest in game", 0},
+		{"My Movie 2022 [HDR] (1080p) [TGx].mp4", "My Movie", 2022},
+		{"NoYearOrTags.mkv", "NoYearOrTags", 0},
+		{"亏成首富从游戏开始 The Richest in Game - S01E11 - 4K.mp4", "亏成首富从游戏开始 The Richest in Game", 0},
 		{"紫川.2024.S02E24.第24集.2160p.WEB-DL.H.265-ColorTV.mkv", "紫川", 2024},
 		{"紫川 (2024) {tmdb-247590}", "紫川", 2024},
-		{"HNTV.Spring.Festival.Gala.FPS.HLG-QHStudio.S01E202-DD5.QHstudIo.6.4K.ts", "hntv spring festival gala", 0},
-		{"Hntv Spring Festival Gala S01e (2026)", "hntv spring festival gala", 2026},
-		{"Motherhood Of Taihang Aac2 Mweb - S01E01-Aac2.Mweb.mkv", "motherhood of taihang", 0},
-		{"For All Mankind Atvp Hhweb - S05E06-DDP5.HHWEB.4K.mkv", "for all mankind", 0},
-		{"Hntv Spring Festival Gala Fps Hlg Qhstudio S01e (2026)", "hntv spring festival gala", 2026},
+		{"HNTV.Spring.Festival.Gala.FPS.HLG-QHStudio.S01E202-DD5.QHstudIo.6.4K.ts", "HNTV Spring Festival Gala", 0},
+		{"Hntv Spring Festival Gala S01e (2026)", "Hntv Spring Festival Gala", 2026},
+		{"Motherhood Of Taihang Aac2 Mweb - S01E01-Aac2.Mweb.mkv", "Motherhood Of Taihang", 0},
+		{"For All Mankind Atvp Hhweb - S05E06-DDP5.HHWEB.4K.mkv", "For All Mankind", 0},
+		{"Hntv Spring Festival Gala Fps Hlg Qhstudio S01e (2026)", "Hntv Spring Festival Gala", 2026},
 	}
 	for _, tc := range cases {
 		t.Run(tc.in, func(t *testing.T) {
@@ -75,7 +75,7 @@ func TestScrapeQueryCandidatesCleanDirtySeriesFolder(t *testing.T) {
 	if len(got) == 0 {
 		t.Fatal("scrapeQueryCandidates returned no candidates")
 	}
-	if got[0] != "motherhood of taihang" {
+	if got[0] != "Motherhood Of Taihang" {
 		t.Fatalf("first query candidate = %q, want cleaned series title; all candidates=%#v", got[0], got)
 	}
 	for _, candidate := range got {

internal/service/service_builder.go

@@ -120,6 +120,8 @@ func (b *serviceContainerBuilder) initContentServices() {
 	b.c.Audit = NewAuditService(b.log, b.repos)
 	b.c.Strm = NewStrmService(b.cfg, b.log, b.repos, b.c.Crypto)
 	b.c.Cloud115 = NewCloud115PlaybackService(b.cfg, b.log, b.repos, b.c.Strm)
+	// 本地 HLS 档位的可用性取决于 ffmpeg 是否可用；未注入时按不可用处理。
+	b.c.Cloud115.SetTranscoder(b.c.Transcoder)
 	// ffmpeg/ffprobe 一键下载安装（data/tools/ffmpeg/）。
 	b.c.FFTools = NewFFmpegToolsService(b.cfg, b.log, b.repos)
 	// 弹幕 hash 识别需要把 strm 指向解析成可拉取的直链/本地路径。

internal/service/strm_service.go

@@ -892,6 +892,10 @@ func truncateStringRuneSafe(s string, maxBytes int) string {
 
 // cleanEntryName 清理单个目录名或文件名中的非法字符、控制字符、尾部点空格及 Windows 保留字，
 // 确保在 Windows (NTFS/FAT)、Linux (ext4/btrfs/xfs) 及 NAS/SMB 挂载环境下均安全可用。
+//
+// 只裁剪**尾部**的点与空格：那是 Windows 明确禁止的部分。前导点是合法且常见的
+// （隐藏目录/文件、.staging 之类），早先按 ". " 双向裁剪会把 `.media` 静默改写成
+// `media`，导致刮削海报边车被写到去掉点后的平行目录、媒体目录反而拿不到图。
 func cleanEntryName(name string, isDir bool) string {
 	name = strings.TrimSpace(name)
 	if name == "" {
@@ -900,7 +904,7 @@ func cleanEntryName(name string, isDir bool) string {
 
 	if isDir {
 		clean := sanitizeFilename(name)
-		clean = strings.Trim(clean, ". ")
+		clean = strings.TrimRight(clean, ". ")
 		if clean == "" {
 			return "unnamed"
 		}
@@ -921,7 +925,7 @@ func cleanEntryName(name string, isDir bool) string {
 	}
 
 	cleanBase := sanitizeFilename(base)
-	cleanBase = strings.Trim(cleanBase, ". ")
+	cleanBase = strings.TrimRight(cleanBase, ". ")
 	if cleanBase == "" {
 		cleanBase = "unnamed"
 	}

internal/service/test_db_test.go

@@ -1,13 +1,24 @@
 package service
 
 import (
+	"reflect"
 	"testing"
 
 	"github.com/glebarez/sqlite"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
+
+	"github.com/truewhile/MeBox/internal/model"
 )
 
+// newServiceTestDB opens an in-memory DB for service tests.
+//
+// The full model set is always migrated, on top of any explicitly requested
+// models. Service code probes tables that a given test may not care about
+// (settings for adult visibility, play_profiles for playback, media for library
+// counts); with a partial schema those probes fail with "no such table" and the
+// default GORM logger floods the test output, burying real failures. Migrating
+// everything keeps fixtures faithful to production and the output quiet.
 func newServiceTestDB(t *testing.T, models ...any) *gorm.DB {
 	t.Helper()
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
@@ -17,10 +28,21 @@ func newServiceTestDB(t *testing.T, models ...any) *gorm.DB {
 	if sqlDB, err := db.DB(); err == nil {
 		t.Cleanup(func() { _ = sqlDB.Close() })
 	}
-	if len(models) > 0 {
-		if err := db.AutoMigrate(models...); err != nil {
-			t.Fatal(err)
+	toMigrate := model.AllModels()
+	seen := make(map[string]struct{}, len(toMigrate)+len(models))
+	for _, m := range toMigrate {
+		seen[reflect.TypeOf(m).String()] = struct{}{}
+	}
+	for _, m := range models {
+		key := reflect.TypeOf(m).String()
+		if _, ok := seen[key]; ok {
+			continue
 		}
+		seen[key] = struct{}{}
+		toMigrate = append(toMigrate, m)
+	}
+	if err := db.AutoMigrate(toMigrate...); err != nil {
+		t.Fatal(err)
 	}
 	return db
 }

internal/service/transcoder.go

@@ -54,6 +54,11 @@ type TranscoderService struct {
 	startGates  sync.Map // mediaID -> *sync.Mutex
 	strmResolve func(ctx context.Context, raw string) (*StrmPlayResult, error)
 	probe       *FFprobeService
+
+	// availMu guards the cached ffmpeg availability used by Available().
+	availMu        sync.Mutex
+	availCheckedAt time.Time
+	availValue     bool
 }
 
 // hlsJob holds the live state of one ffmpeg run.
@@ -99,6 +104,37 @@ func NewTranscoderService(cfg *config.Config, log *zap.Logger, repo *repository.
 	}
 }
 
+// transcodeAvailabilityTTL bounds how long an Available() result is reused.
+// Validating ffmpeg actually spawns it, and /playback is polled on every player
+// load, so the answer is cached briefly. It stays short so a freshly installed
+// ffmpeg becomes usable without restarting the server.
+const transcodeAvailabilityTTL = 20 * time.Second
+
+// Available reports whether HLS transcoding can run right now: transcoding must
+// be enabled by configuration and a usable ffmpeg must resolve. Callers use it to
+// stop advertising local HLS renditions that would only fail with a 500.
+func (t *TranscoderService) Available() bool {
+	if t == nil || t.cfg == nil {
+		return false
+	}
+	if !t.cfg.Transcoder.Enabled {
+		return false
+	}
+	t.availMu.Lock()
+	defer t.availMu.Unlock()
+	if !t.availCheckedAt.IsZero() && time.Since(t.availCheckedAt) < transcodeAvailabilityTTL {
+		return t.availValue
+	}
+	_, err := t.resolveFFmpegPath()
+	available := err == nil
+	if !available && t.log != nil {
+		t.log.Debug("local HLS renditions unavailable", zap.Error(err))
+	}
+	t.availValue = available
+	t.availCheckedAt = time.Now()
+	return available
+}
+
 // HLSDir is the per-media directory that holds index.m3u8 + segment files.
 func (t *TranscoderService) HLSDir(mediaID string) string {
 	return filepath.Join(t.cfg.Cache.CacheDir, "hls", mediaID)

internal/service/transcoder_availability_test.go

@@ -0,0 +1,67 @@
+package service
+
+import (
+	"path/filepath"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+)
+
+// Available() gates the local HLS renditions advertised to the player, so it must
+// be false both when transcoding is disabled by configuration and when no usable
+// ffmpeg can be resolved.
+func TestTranscoderAvailableGatesOnConfigAndBinary(t *testing.T) {
+	cases := []struct {
+		name       string
+		enabled    bool
+		ffmpegPath string
+	}{
+		{name: "disabled by config", enabled: false, ffmpegPath: filepath.Join(t.TempDir(), "missing-ffmpeg")},
+		{name: "no ffmpeg binary", enabled: true, ffmpegPath: filepath.Join(t.TempDir(), "missing-ffmpeg")},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &config.Config{}
+			cfg.Transcoder.Enabled = tc.enabled
+			cfg.App.FFmpegPath = tc.ffmpegPath
+			svc := NewTranscoderService(cfg, zap.NewNop(), nil, NewHub(zap.NewNop()))
+
+			if svc.Available() {
+				t.Fatalf("Available() = true, want false (enabled=%v path=%q)", tc.enabled, tc.ffmpegPath)
+			}
+		})
+	}
+}
+
+// A nil service or nil config must not panic: playback info is built on paths
+// where wiring may be partial.
+func TestTranscoderAvailableNilSafe(t *testing.T) {
+	var nilSvc *TranscoderService
+	if nilSvc.Available() {
+		t.Fatal("nil transcoder should report unavailable")
+	}
+	svc := &TranscoderService{}
+	if svc.Available() {
+		t.Fatal("transcoder without config should report unavailable")
+	}
+}
+
+// Playback info must not advertise local HLS renditions when the playback service
+// has no transcoder wired in.
+func TestCloud115PlaybackServiceWithoutTranscoderMarksLocalQualitiesUnavailable(t *testing.T) {
+	svc := NewCloud115PlaybackService(&config.Config{}, zap.NewNop(), nil, nil)
+	if svc.localTranscodeAvailable() {
+		t.Fatal("playback service without a transcoder must report local HLS unavailable")
+	}
+	options := LocalQualityOptions(nil, svc.localTranscodeAvailable())
+	if len(options) == 0 {
+		t.Fatal("local quality presets should still be listed for the UI")
+	}
+	for _, option := range options {
+		if option.Available {
+			t.Fatalf("quality %s advertised as available without a transcoder", option.ID)
+		}
+	}
+}

internal/service/walk.go

@@ -14,14 +14,22 @@ type walkInfo struct {
 }
 
 // walk traverses root depth-first calling fn for every entry. Hidden
-// directories (starting with ".") are skipped.
+// directories (starting with ".") below the root are skipped.
+//
+// The root itself is deliberately exempt from the hidden-directory rule.
+// WalkDir reports the root with its own base name, so a root such as
+// "/media/.staging" used to match the hidden check and yield filepath.SkipDir
+// immediately — the entire tree was skipped silently, with no error and no
+// warning. A library or organize source may legitimately live in a
+// dot-prefixed directory, so only children are filtered.
 func walk(root string, fn func(string, walkInfo) error) error {
-	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+	rootPath := filepath.Clean(root)
+	return filepath.WalkDir(rootPath, func(path string, d fs.DirEntry, err error) error {
 		if err != nil {
 			return nil // best effort — keep walking
 		}
 		name := d.Name()
-		if d.IsDir() && name != "." && len(name) > 1 && name[0] == '.' {
+		if d.IsDir() && path != rootPath && name != "." && len(name) > 1 && name[0] == '.' {
 			return filepath.SkipDir
 		}
 		info := walkInfo{isDir: d.IsDir()}

internal/service/walk_dotdir_test.go

@@ -0,0 +1,115 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func writeWalkFile(t *testing.T, path string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %s: %v", filepath.Dir(path), err)
+	}
+	if err := os.WriteFile(path, []byte("data"), 0o644); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}
+
+func collectWalkPaths(t *testing.T, root string) []string {
+	t.Helper()
+	var seen []string
+	if err := walk(root, func(path string, info walkInfo) error {
+		if !info.isDir {
+			seen = append(seen, path)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("walk %s: %v", root, err)
+	}
+	return seen
+}
+
+// A dot-prefixed walk root must not be treated as a hidden directory: doing so
+// skipped the whole tree silently, so a library rooted at e.g. "/media/.staging"
+// indexed nothing and the organizer reported "0 organized" with no error.
+func TestWalkIncludesDotPrefixedRoot(t *testing.T) {
+	parent := t.TempDir()
+	dotRoot := filepath.Join(parent, ".dotroot")
+	want := filepath.Join(dotRoot, "Movie (2021)", "Movie (2021).mkv")
+	writeWalkFile(t, want)
+
+	got := collectWalkPaths(t, dotRoot)
+	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(want) {
+		t.Fatalf("walk over dot-prefixed root = %#v, want the one file inside it", got)
+	}
+}
+
+// Hidden directories *below* the root are still skipped.
+func TestWalkStillSkipsHiddenChildDirectories(t *testing.T) {
+	root := t.TempDir()
+	visible := filepath.Join(root, "Movie (2021)", "Movie (2021).mkv")
+	hidden := filepath.Join(root, ".trash", "Old Movie.mkv")
+	deepHidden := filepath.Join(root, "Season 01", ".thumbnails", "thumb.mkv")
+	writeWalkFile(t, visible)
+	writeWalkFile(t, hidden)
+	writeWalkFile(t, deepHidden)
+
+	got := collectWalkPaths(t, root)
+	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(visible) {
+		t.Fatalf("walk = %#v, want only the visible file", got)
+	}
+}
+
+// End-to-end: a library whose root directory starts with "." must be scanned.
+func TestScanLibraryIndexesDotPrefixedRoot(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := filepath.Join(t.TempDir(), ".media")
+	lib := model.Library{Name: "Movies", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	writeWalkFile(t, filepath.Join(root, "Movie (2021)", "Movie (2021).mkv"))
+
+	res, err := sc.ScanLibrary(t.Context(), lib.ID)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if res.Added != 1 {
+		t.Fatalf("scan added=%d (errors=%v), want 1 for a dot-prefixed library root", res.Added, res.Errors)
+	}
+	if got := countMedia(t, repos); got != 1 {
+		t.Fatalf("media count = %d, want 1", got)
+	}
+}
+
+// End-to-end: organizing from a dot-prefixed source directory must find files.
+func TestOrganizeDirectoryReadsDotPrefixedSource(t *testing.T) {
+	repos := newOrganizerTestRepo(t)
+	cfg := &config.Config{}
+	cfg.Organizer.SmartClassify = true
+	organizer := NewOrganizerService(cfg, zap.NewNop(), repos)
+
+	root := t.TempDir()
+	src := filepath.Join(root, ".downloads")
+	dest := filepath.Join(root, "media")
+	writeWalkFile(t, filepath.Join(src, "Oppenheimer.2023.2160p.WEB-DL.H265", "oppenheimer-2160p.mkv"))
+
+	res, err := organizer.OrganizeDirectory(t.Context(), OrganizeOptions{
+		SourcePath:   src,
+		DestPath:     dest,
+		TransferMode: TransferCopy,
+	})
+	if err != nil {
+		t.Fatalf("organize directory: %v", err)
+	}
+	if res.Organized != 1 {
+		t.Fatalf("organized=%d skipped=%d errors=%v, want the file under a dot-prefixed source to be organized",
+			res.Organized, res.Skipped, res.Errors)
+	}
+}