添加VR360播放功能

internal/service/media_listing.go

@@ -2,7 +2,6 @@ package service
 
 import (
 	"context"
-	"sort"
 	"strings"
 	"time"
 
@@ -179,9 +178,18 @@ func (s *MediaService) listVersionSiblings(ctx context.Context, media *model.Med
 		libraryIDs = []string{media.LibraryID}
 	}
 	filter := repository.MediaQueryFilter{IncludeNSFW: true}
-	candidates, narrowed, err := s.repo.Media.ListVersionCandidates(ctx, libraryIDs, *media, 5000)
-	if err != nil {
-		return nil, err
+	// 成人条目按番号分组，而番号常常只存在于路径/标题里：本地 NFO 来源的分片
+	// 没有 douban_id/thetvdb_id（MetaTube 刮削出来的那几个才有）。若仍按外部
+	// ID 预先收窄候选集，同番号的其它分片会被 SQL 直接排除，表现就是库里折叠
+	// 出了 N 个版本、详情页却只列出带 ID 的那几个。因此成人条目不预先收窄，
+	// 直接在该库范围内比对版本键。
+	var candidates []model.Media
+	narrowed := false
+	if mediaAdultGroupCode(*media) == "" {
+		candidates, narrowed, err = s.repo.Media.ListVersionCandidates(ctx, libraryIDs, *media, 5000)
+		if err != nil {
+			return nil, err
+		}
 	}
 	if !narrowed {
 		candidates, err = s.repo.Media.ListByLibrariesFilteredNoCount(ctx, libraryIDs, 0, 5000, filter)
@@ -199,14 +207,6 @@ func (s *MediaService) listVersionSiblings(ctx context.Context, media *model.Med
 	if len(matched) == 0 {
 		return []model.Media{*media}, nil
 	}
-	sort.SliceStable(matched, func(i, j int) bool {
-		if matched[i].ID == media.ID {
-			return true
-		}
-		if matched[j].ID == media.ID {
-			return false
-		}
-		return betterMediaVersion(matched[i], matched[j])
-	})
+	sortMediaVersionsForDisplay(matched)
 	return matched, nil
 }

internal/service/media_versions.go

@@ -3,7 +3,9 @@ package service
 import (
 	"fmt"
 	"path/filepath"
+	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 
 	"github.com/truewhile/MeBox/internal/model"
@@ -76,34 +78,28 @@ func groupMediaVersions(items []model.Media) []MediaItem {
 		return nil
 	}
 	type group struct {
-		key     string
-		primary model.Media
-		rows    []model.Media
+		key  string
+		rows []model.Media
 	}
 	groups := make([]group, 0, len(items))
 	byKey := make(map[string]int, len(items))
 	for _, item := range items {
 		key := mediaVersionGroupKey(item)
 		if key == "" {
-			groups = append(groups, group{primary: item, rows: []model.Media{item}})
+			groups = append(groups, group{rows: []model.Media{item}})
 			continue
 		}
 		if idx, ok := byKey[key]; ok {
 			groups[idx].rows = append(groups[idx].rows, item)
-			if betterMediaVersion(item, groups[idx].primary) {
-				groups[idx].primary = item
-			}
 			continue
 		}
 		byKey[key] = len(groups)
-		groups = append(groups, group{key: key, primary: item, rows: []model.Media{item}})
+		groups = append(groups, group{key: key, rows: []model.Media{item}})
 	}
 	out := make([]MediaItem, 0, len(groups))
 	for _, g := range groups {
-		sort.SliceStable(g.rows, func(i, j int) bool {
-			return betterMediaVersion(g.rows[i], g.rows[j])
-		})
-		item := MediaItem{Media: g.primary}
+		sortMediaVersionsForDisplay(g.rows)
+		item := MediaItem{Media: g.rows[0]}
 		if len(g.rows) > 1 {
 			item.Versions = g.rows
 		}
@@ -193,6 +189,18 @@ func mediaVersionGroupKey(m model.Media) string {
 		return mediaVersionStemGroupKey(m, libKey)
 	}
 
+	// 成人条目按番号折叠。在线刮削（MetaTube）会把番号与 provider「借用」
+	// 存进 douban_id/thetvdb_id，本地 NFO 路径则拿不到这两个字段；一旦按
+	// 外部 ID 分组，同一部片的各个分片就会因为元数据来源不同（在线刮削 vs
+	// 本地 NFO）裂成两张标题相同的卡。番号取自原文件名/路径/标题，与元数据
+	// 来源无关，因此这里统一用番号做版本身份。
+	if code := mediaAdultGroupCode(m); code != "" {
+		if libKey == "" {
+			libKey = "_"
+		}
+		return fmt.Sprintf("adult:%s:%s", libKey, code)
+	}
+
 	switch {
 	case m.TMDbID > 0:
 		if libKey != "" {
@@ -267,6 +275,44 @@ func mediaVersionGroupKey(m model.Media) string {
 	return fmt.Sprintf("movie:%s:%d", title, year)
 }
 
+// mediaAdultGroupCode 返回成人条目的番号，作为与元数据来源无关的版本身份。
+//
+// 只在已经确认是成人条目（NSFW）时才返回番号：番号本身来自原文件名/路径/
+// 标题，不会随「在线刮削（MetaTube 把番号与 provider 借用进 douban_id/
+// thetvdb_id）」还是「本地 NFO（不带外部 ID）」而改变，因此两条来源能算出
+// 同一个键。未标记 NSFW 的条目仍走标题分组，普通影视库里 "The Matrix 1999"
+// 这类文件名不会被当成番号。
+func mediaAdultGroupCode(m model.Media) string {
+	if !m.NSFW {
+		return ""
+	}
+	code := firstText(
+		normalizeAdultCode(m.OriginalName),
+		AdultCodeFromMediaPath(m.Path),
+		normalizeAdultCode(m.Title),
+	)
+	if code == "" {
+		return ""
+	}
+	return canonicalAdultGroupCode(code)
+}
+
+// canonicalAdultGroupCode 去掉番号数字部分的补零，让 IPVR-00192 与 IPVR-192
+// 这类同一部片的不同写法落到同一个分组键上。无法解析数字的番号原样返回
+// （如 FC2-PPV-4701981）。
+func canonicalAdultGroupCode(code string) string {
+	code = strings.ToUpper(strings.TrimSpace(code))
+	prefix, digits, ok := strings.Cut(code, "-")
+	if !ok {
+		return code
+	}
+	value, err := strconv.Atoi(digits)
+	if err != nil {
+		return code
+	}
+	return prefix + "-" + strconv.Itoa(value)
+}
+
 // mediaVersionStemGroupKey 按「库 + 父目录 + 文件词干」折叠多版本
 // （如 竞女01.mkv.strm 与 竞女01.mp4.strm）。
 func mediaVersionStemGroupKey(m model.Media, libKey string) string {
@@ -300,8 +346,11 @@ func mediaVersionFileStem(name string) string {
 }
 
 // MediaVersionLabel 生成版本切换展示名（分辨率 / 容器 / 编码 / 体积 / 文件名）。
+// 当只有容器等无法区分多版本的信息时，回退到清理后的文件名。
 func MediaVersionLabel(m model.Media) string {
 	parts := make([]string, 0, 4)
+	isStrm := strings.HasSuffix(strings.ToLower(strings.TrimSpace(m.Path)), ".strm") ||
+		strings.TrimSpace(m.STRMURL) != ""
 	if m.Height > 0 {
 		parts = append(parts, fmt.Sprintf("%dp", m.Height))
 	} else if m.Width > 0 {
@@ -317,17 +366,91 @@ func MediaVersionLabel(m model.Media) string {
 	if codec := strings.TrimSpace(m.VideoCodec); codec != "" {
 		parts = append(parts, strings.ToUpper(codec))
 	}
-	if m.SizeBytes > 0 {
+	// STRM 占位体积（通常几十到几百字节）不能区分分片，跳过。
+	placeholderSize := isStrm && m.SizeBytes > 0 && m.SizeBytes < 1024*1024
+	if m.SizeBytes > 0 && !placeholderSize {
 		parts = append(parts, formatMediaSize(m.SizeBytes))
 	}
-	if len(parts) > 0 {
+	if len(parts) > 0 && !mediaVersionLabelIndistinct(parts) {
 		return strings.Join(parts, " · ")
 	}
-	base := filepath.Base(strings.ReplaceAll(strings.TrimSpace(m.Path), "\\", "/"))
-	if base == "" || base == "." {
-		return firstNonEmpty(m.Title, m.OriginalName, m.ID)
+	if cleaned := cleanMediaVersionFilename(m.Path); cleaned != "" {
+		return cleaned
 	}
-	return base
+	return firstNonEmpty(m.Title, m.OriginalName, m.ID)
+}
+
+func mediaVersionLabelIndistinct(parts []string) bool {
+	if len(parts) == 0 {
+		return true
+	}
+	for _, part := range parts {
+		upper := strings.ToUpper(strings.TrimSpace(part))
+		if upper == "" || upper == "云端直链" || upper == "STRM" {
+			continue
+		}
+		if _, ok := videoExtensions["."+strings.ToLower(upper)]; ok {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+func cleanMediaVersionFilename(path string) string {
+	base := filepath.Base(strings.ReplaceAll(strings.TrimSpace(path), "\\", "/"))
+	if base == "" || base == "." {
+		return ""
+	}
+	stem := mediaFileStem(base)
+	stem = strings.ReplaceAll(stem, "_", " ")
+	stem = strings.ReplaceAll(stem, ".", " ")
+	return strings.Join(strings.Fields(stem), " ")
+}
+
+// mediaPartNumber 从路径提取分片序号（part1 / cd2 / -3）。
+// 裸后缀只认 1–2 位数字，避免把年份 2024 当成 part。
+func mediaPartNumber(path string) (int, bool) {
+	stem := mediaFileStem(filepath.Base(strings.ReplaceAll(strings.TrimSpace(path), "\\", "/")))
+	if stem == "" {
+		return 0, false
+	}
+	lower := strings.ToLower(stem)
+	for _, re := range mediaPartNumberPatterns {
+		if m := re.FindStringSubmatch(lower); len(m) == 2 {
+			n, err := strconv.Atoi(m[1])
+			if err == nil && n > 0 {
+				return n, true
+			}
+		}
+	}
+	return 0, false
+}
+
+var mediaPartNumberPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`(?:^|[.\-_])part[\s._-]*(\d{1,3})$`),
+	regexp.MustCompile(`(?:^|[.\-_])(?:cd|disc|disk)[\s._-]*(\d{1,3})$`),
+	regexp.MustCompile(`[-_](\d{1,2})$`),
+}
+
+func sortMediaVersionsForDisplay(rows []model.Media) {
+	sort.SliceStable(rows, func(i, j int) bool {
+		return compareMediaVersionsForDisplay(rows[i], rows[j])
+	})
+}
+
+// compareMediaVersionsForDisplay：有分片号时按 1→2→3… 升序；否则按画质/体积择优。
+func compareMediaVersionsForDisplay(a, b model.Media) bool {
+	pa, oka := mediaPartNumber(a.Path)
+	pb, okb := mediaPartNumber(b.Path)
+	if oka && okb {
+		if pa != pb {
+			return pa < pb
+		}
+	} else if oka != okb {
+		return oka
+	}
+	return betterMediaVersion(a, b)
 }
 
 func mediaVersionContainerFromPath(path, strmURL string) string {

internal/service/media_versions_test.go

@@ -442,3 +442,298 @@ func TestMediaVersionLabelUsesContainerAndSize(t *testing.T) {
 		t.Fatalf("unexpected label %q", label)
 	}
 }
+
+func TestMediaPartNumberFromPath(t *testing.T) {
+	cases := []struct {
+		path string
+		want int
+		ok   bool
+	}{
+		{"/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part1.strm", 1, true},
+		{"/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part2.strm", 2, true},
+		{"/media/云下载/sivr-270/sivr-270-1.strm", 1, true},
+		{"/media/云下载/sivr-270/sivr-270-7.strm", 7, true},
+		{"/media/云下载/fc2/FC2PPV-4701981-cd2.strm", 2, true},
+		{"/media/Movies/Inception.2010.1080p.BluRay.x264.mkv", 0, false},
+		{"/media/Movies/Movie.2024.mkv", 0, false},
+	}
+	for _, tc := range cases {
+		got, ok := mediaPartNumber(tc.path)
+		if ok != tc.ok || got != tc.want {
+			t.Fatalf("mediaPartNumber(%q) = (%d, %v), want (%d, %v)", tc.path, got, ok, tc.want, tc.ok)
+		}
+	}
+}
+
+func TestGroupMediaVersionsSortsPartsAscending(t *testing.T) {
+	rows := []model.Media{
+		{
+			Base:      model.Base{ID: "p3"},
+			LibraryID: "cloud",
+			Title:     "SIVR-270",
+			Path:      "/media/云下载/sivr-270/sivr-270-3.strm",
+			Year:      2023,
+			NSFW:      true,
+			SizeBytes: 300,
+		},
+		{
+			Base:      model.Base{ID: "p1"},
+			LibraryID: "cloud",
+			Title:     "SIVR-270",
+			Path:      "/media/云下载/sivr-270/sivr-270-1.strm",
+			Year:      2023,
+			NSFW:      true,
+			SizeBytes: 100,
+		},
+		{
+			Base:      model.Base{ID: "p2"},
+			LibraryID: "cloud",
+			Title:     "SIVR-270",
+			Path:      "/media/云下载/sivr-270/sivr-270-2.strm",
+			Year:      2023,
+			NSFW:      true,
+			SizeBytes: 200,
+		},
+	}
+	grouped := groupMediaVersions(rows)
+	if len(grouped) != 1 || len(grouped[0].Versions) != 3 {
+		t.Fatalf("grouped = %#v", grouped)
+	}
+	want := []string{"p1", "p2", "p3"}
+	for i, id := range want {
+		if grouped[0].Versions[i].ID != id {
+			t.Fatalf("versions[%d] = %q, want %q (order %#v)", i, grouped[0].Versions[i].ID, id, grouped[0].Versions)
+		}
+	}
+	if grouped[0].ID != "p1" {
+		t.Fatalf("primary = %q, want p1 (first part)", grouped[0].ID)
+	}
+}
+
+func TestMediaVersionLabelFallsBackToFilenameWhenIndistinct(t *testing.T) {
+	label := MediaVersionLabel(model.Media{
+		Title:     "SIVR-270-【VR】河北彩花",
+		Path:      "/media/云下载/sivr-270/sivr-270-1.strm",
+		SizeBytes: 157,
+		STRMURL:   "/api/strm/play/cloud115/video.mp4?pickcode=a",
+	})
+	if !strings.Contains(label, "sivr-270-1") {
+		t.Fatalf("indistinct strm label should fall back to filename, got %q", label)
+	}
+	if strings.EqualFold(label, "MP4") || strings.Contains(label, "云端") {
+		t.Fatalf("should not keep generic-only label %q", label)
+	}
+}
+
+// SIVR-270 现场：一部分分片走在线刮削（MetaTube 把番号/provider 借用进
+// douban_id/thetvdb_id），另一部分只从本地 NFO 拿到标题（没有外部 ID）。
+// 按外部 ID 分组会把它们裂成两张标题完全相同的卡，必须按番号折成一张。
+func TestGroupMediaVersionsMergesAdultPartsAcrossMetadataSources(t *testing.T) {
+	online := model.Media{
+		Base:         model.Base{ID: "sivr-270-2"},
+		LibraryID:    "cloud",
+		Title:        "SIVR-270-【VR】河北彩花",
+		OriginalName: "SIVR-270",
+		Path:         "/media/云下载/sivr-270/sivr-270-2.strm",
+		Year:         2023,
+		NSFW:         true,
+		DoubanID:     "SIVR-270",
+		TheTVDBID:    "JavBus",
+		ScrapeStatus: "matched",
+		SizeBytes:    200,
+	}
+	fromNFO := model.Media{
+		Base:         model.Base{ID: "sivr-270-3"},
+		LibraryID:    "cloud",
+		Title:        "SIVR-270-【VR】河北彩花",
+		OriginalName: "SIVR-270",
+		Path:         "/media/云下载/sivr-270/sivr-270-3.strm",
+		Year:         2023,
+		NSFW:         true,
+		ScrapeStatus: "matched",
+		SizeBytes:    100,
+	}
+
+	grouped := groupMediaVersions([]model.Media{online, fromNFO})
+	if len(grouped) != 1 {
+		t.Fatalf("grouped len = %d, want 1: %#v", len(grouped), grouped)
+	}
+	if len(grouped[0].Versions) != 2 {
+		t.Fatalf("versions len = %d, want 2", len(grouped[0].Versions))
+	}
+	if grouped[0].Path != online.Path {
+		t.Fatalf("larger part should stay primary, got %q", grouped[0].Path)
+	}
+}
+
+func TestGroupMediaVersionsKeepsDifferentAdultCodesSeparate(t *testing.T) {
+	rows := []model.Media{
+		{
+			Base:      model.Base{ID: "sivr-270"},
+			LibraryID: "cloud",
+			Title:     "SIVR-270 作品",
+			Path:      "/media/云下载/sivr-270/sivr-270-1.strm",
+			Year:      2023,
+			NSFW:      true,
+		},
+		{
+			Base:      model.Base{ID: "sivr-271"},
+			LibraryID: "cloud",
+			Title:     "SIVR-271 作品",
+			Path:      "/media/云下载/sivr-271/sivr-271-1.strm",
+			Year:      2023,
+			NSFW:      true,
+		},
+	}
+	grouped := groupMediaVersions(rows)
+	if len(grouped) != 2 {
+		t.Fatalf("different adult codes must stay separate: %#v", grouped)
+	}
+}
+
+// 同一部片的两种写法：路径里的 IPVR-00192 与刮削回来的 IPVR-192 必须归一。
+func TestGroupMediaVersionsMergesAdultCodesIgnoringZeroPadding(t *testing.T) {
+	scraped := model.Media{
+		Base:         model.Base{ID: "ipvr-192-part2"},
+		LibraryID:    "cloud",
+		Title:        "IPVR-192-相沢みなみ",
+		OriginalName: "IPVR-192",
+		Path:         "/media/云下载/ipvr00192pl/scraped/part2.strm",
+		Year:         2022,
+		NSFW:         true,
+		ScrapeStatus: "matched",
+		SizeBytes:    200,
+	}
+	fromPath := model.Media{
+		Base:      model.Base{ID: "ipvr-00192-part1"},
+		LibraryID: "cloud",
+		Title:     "fbzip com@ipvr00192",
+		Path:      "/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part1.strm",
+		Year:      2022,
+		NSFW:      true,
+		SizeBytes: 100,
+	}
+	grouped := groupMediaVersions([]model.Media{scraped, fromPath})
+	if len(grouped) != 1 || len(grouped[0].Versions) != 2 {
+		t.Fatalf("zero padded code must fold into one item: %#v", grouped)
+	}
+}
+
+func TestGroupMediaVersionsMergesAdultPartsWithBorrowedMetaTubeIDs(t *testing.T) {
+	// IPVR-00192 现场：两个 part 标题、年份完全一样，但 part2 是走 MetaTube
+	// 刮削的（番号/provider 被借用进 douban_id/thetvdb_id），part1 只有本地
+	// NFO 身份、两个字段为空。旧逻辑按外部 ID 分组会裂成两张卡。
+	part1 := model.Media{
+		Base:         model.Base{ID: "ipvr-00192-part1"},
+		LibraryID:    "cloud",
+		Title:        "IPVR-00192-IPVR-192-【VR】相沢みなみ",
+		OriginalName: "IPVR-00192",
+		Path:         "/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part1.strm",
+		Year:         2022,
+		NSFW:         true,
+		ScrapeStatus: "matched",
+		SizeBytes:    100,
+	}
+	part2 := part1
+	part2.ID = "ipvr-00192-part2"
+	part2.Path = "/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part2.strm"
+	part2.DoubanID = "ipvr00192"
+	part2.TheTVDBID = "JAV321"
+	part2.SizeBytes = 200
+
+	grouped := groupMediaVersions([]model.Media{part1, part2})
+	if len(grouped) != 1 {
+		t.Fatalf("grouped len = %d, want 1: %#v", len(grouped), grouped)
+	}
+	if len(grouped[0].Versions) != 2 {
+		t.Fatalf("versions len = %d, want 2", len(grouped[0].Versions))
+	}
+	if grouped[0].Versions[0].ID != "ipvr-00192-part1" || grouped[0].Versions[1].ID != "ipvr-00192-part2" {
+		t.Fatalf("versions should be part1 then part2, got %#v", grouped[0].Versions)
+	}
+}
+
+func TestGetMediaItemListsAdultVersionsAcrossMetadataSources(t *testing.T) {
+	db := newServiceTestDB(t, &model.Library{}, &model.Media{})
+	repos := repository.New(db)
+	lib := model.Library{Name: "云下载", Path: "/media/云下载", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatal(err)
+	}
+	rows := []model.Media{
+		{
+			// 走 MetaTube 刮削的分片：番号/provider 被借用进 douban/thetvdb。
+			LibraryID:    lib.ID,
+			Title:        "SIVR-270-【VR】河北彩花",
+			OriginalName: "SIVR-270",
+			Path:         "/media/云下载/sivr-270/sivr-270-1.strm",
+			Year:         2023,
+			NSFW:         true,
+			DoubanID:     "SIVR-270",
+			TheTVDBID:    "JavBus",
+			ScrapeStatus: "matched",
+			SizeBytes:    200,
+		},
+		{
+			// 只有本地 NFO 身份的分片：两个外部 ID 都为空。
+			LibraryID:    lib.ID,
+			Title:        "SIVR-270-【VR】河北彩花",
+			OriginalName: "SIVR-270",
+			Path:         "/media/云下载/sivr-270/sivr-270-4.strm",
+			Year:         2023,
+			NSFW:         true,
+			ScrapeStatus: "matched",
+			SizeBytes:    100,
+		},
+	}
+	if err := db.Create(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	svc := NewMediaService(&config.Config{}, zap.NewNop(), repos).
+		SetRuntimeCache(NewRuntimeCacheService(&config.Config{}, zap.NewNop()))
+	item, err := svc.GetMediaItem(t.Context(), rows[0].ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if item == nil || len(item.Versions) != 2 {
+		// 详情页版本列表不能只按外部 ID 收窄，否则没有 ID 的分片会消失。
+		t.Fatalf("versions = %#v, want both parts", item)
+	}
+}
+
+func TestMediaAdultGroupCodeRequiresNSFW(t *testing.T) {
+	cases := []struct {
+		name string
+		m    model.Media
+		want string
+	}{
+		{
+			name: "普通影片名里的字母+数字不当番号",
+			m:    model.Media{Title: "Spider-Man 2008 1080p", Path: "/media/Movies/Spider-Man 2008 1080p.mkv"},
+			want: "",
+		},
+		{
+			name: "未识别成人的条目即使文件名像番号也不折叠",
+			m:    model.Media{Title: "SIVR-270", Path: "/media/云下载/sivr-270/sivr-270-1.strm"},
+			want: "",
+		},
+		{
+			name: "已标记 NSFW 时按番号分组",
+			m:    model.Media{NSFW: true, Title: "sivr 270", Path: "/media/云下载/sivr-270/sivr-270-1.strm"},
+			want: "SIVR-270",
+		},
+		{
+			name: "站点前缀里带补零的番号会归一",
+			m:    model.Media{NSFW: true, Title: "fbzip com@ipvr00192", Path: "/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part1.strm"},
+			want: "IPVR-192",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := mediaAdultGroupCode(tc.m); got != tc.want {
+				t.Fatalf("mediaAdultGroupCode = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

internal/service/nfo.go

@@ -18,6 +18,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"go.uber.org/zap"
@@ -48,9 +49,13 @@ type movieNFO struct {
 	Poster   string   `xml:"thumb,omitempty"`
 	Fanart   string   `xml:"fanart,omitempty"`
 	TMDb     int      `xml:"tmdbid,omitempty"`
-	Genre    []string `xml:"genre,omitempty"`
-	Country  []string `xml:"country,omitempty"`
-	Language []string `xml:"language,omitempty"`
+	// UniqueIDs 让 sidecar 能把 MeBox 自己用的外部 ID 原样带回来。缺了它，
+	// 「在线刮削 → 写 NFO → 重扫读 NFO」会丢掉 douban/thetvdb（成人条目借用
+	// 这两个字段存番号/provider），同一部片的两条来源就会算出不同的版本键。
+	UniqueIDs []nfoUniqueID `xml:"uniqueid,omitempty"`
+	Genre     []string      `xml:"genre,omitempty"`
+	Country   []string      `xml:"country,omitempty"`
+	Language  []string      `xml:"language,omitempty"`
 }
 
 type episodeNFO struct {
@@ -167,17 +172,18 @@ func WriteMediaNFO(m *model.Media) (string, error) {
 			}
 		}
 		doc = movieNFO{
-			Title:    title,
-			Original: original,
-			Year:     m.Year,
-			Plot:     m.Overview,
-			Rating:   m.Rating,
-			Poster:   m.PosterURL,
-			Fanart:   m.BackdropURL,
-			TMDb:     m.TMDbID,
-			Genre:    splitNFOList(m.Genres),
-			Country:  splitNFOList(m.Countries),
-			Language: splitNFOList(m.Languages),
+			Title:     title,
+			Original:  original,
+			Year:      m.Year,
+			Plot:      m.Overview,
+			Rating:    m.Rating,
+			Poster:    m.PosterURL,
+			Fanart:    m.BackdropURL,
+			TMDb:      m.TMDbID,
+			UniqueIDs: nfoExternalUniqueIDs(m),
+			Genre:     splitNFOList(m.Genres),
+			Country:   splitNFOList(m.Countries),
+			Language:  splitNFOList(m.Languages),
 		}
 	}
 	out, err := xml.MarshalIndent(doc, "", "  ")
@@ -202,3 +208,27 @@ func splitNFOList(value string) []string {
 	}
 	return out
 }
+
+// nfoExternalUniqueIDs 把 MeBox 使用的外部 ID 写进 sidecar，供自己重扫时读回
+// （metadataFromDoc 会按 type 还原成 bangumi/douban/thetvdb 字段）。
+// TMDb 走 <tmdbid>，单集 NFO 不写唯一 ID：单集 ID 属于单集，写进整剧身份会把
+// 同一部剧拆成多张卡（见 mergeEpisodeMetadata 的约束说明）。
+func nfoExternalUniqueIDs(m *model.Media) []nfoUniqueID {
+	if m == nil {
+		return nil
+	}
+	out := make([]nfoUniqueID, 0, 3)
+	if m.BangumiID > 0 {
+		out = append(out, nfoUniqueID{Type: "bangumi", Value: strconv.Itoa(m.BangumiID)})
+	}
+	if id := strings.TrimSpace(m.DoubanID); id != "" {
+		out = append(out, nfoUniqueID{Type: "douban", Value: id})
+	}
+	if id := strings.TrimSpace(m.TheTVDBID); id != "" {
+		out = append(out, nfoUniqueID{Type: "thetvdb", Value: id})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}

internal/service/nfo_test.go

@@ -100,3 +100,51 @@ func TestWriteMediaNFOAdultTitleWithCode(t *testing.T) {
 		t.Fatalf("expected originaltitle with code, got:\n%s", text)
 	}
 }
+
+func TestWriteMediaNFORoundTripsExternalUniqueIDs(t *testing.T) {
+	root := t.TempDir()
+	mediaPath := filepath.Join(root, "云下载", "sivr-270", "sivr-270-1.strm")
+	if err := os.MkdirAll(filepath.Dir(mediaPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(mediaPath, []byte("strm"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	dst, err := WriteMediaNFO(&model.Media{
+		Title:        "SIVR-270-河北彩花",
+		OriginalName: "SIVR-270",
+		Path:         mediaPath,
+		Year:         2023,
+		NSFW:         true,
+		DoubanID:     "SIVR-270",
+		TheTVDBID:    "JavBus",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, err := os.ReadFile(dst)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(body)
+	// 成人条目把番号/provider 借用存在 douban/thetvdb 两列；sidecar 必须把它们
+	// 带回来，否则「在线刮削 → 写 NFO → 重扫读 NFO」之后同一部片会被按不同
+	// 分组键拆成多张卡。
+	for _, want := range []string{
+		`<uniqueid type="douban">SIVR-270</uniqueid>`,
+		`<uniqueid type="thetvdb">JavBus</uniqueid>`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("sidecar missing %s, got:\n%s", want, text)
+		}
+	}
+
+	meta, err := ReadLocalMetadata(mediaPath, "", false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if meta == nil || meta.DoubanID != "SIVR-270" || meta.TheTVDBID != "JavBus" {
+		t.Fatalf("external ids did not round trip: %#v", meta)
+	}
+}

web/src/components/PlayerControls.tsx

@@ -16,6 +16,7 @@ import {
   PictureInPicture,
   Play,
   Rewind,
+  Rotate3d,
   SkipBack,
   SkipForward,
   Timer,
@@ -24,6 +25,7 @@ import {
 } from 'lucide-react'
 import type { SubtitleTrack } from '../api/subtitles'
 import type { PlaybackQuality } from '../types'
+import type { Vr360Profile } from '../utils/vr360'
 import {
   formatPlaybackRate,
   normalizePlaybackRate,
@@ -116,6 +118,11 @@ type PlayerControlsProps = {
   selectedQuality?: string
   onSelectQuality?: (quality: PlaybackQuality) => void
   showQuality?: boolean
+  /** VR 全景播放配置；非 null 表示当前处于 VR 模式。 */
+  vr360?: Vr360Profile | null
+  /** 是否由文件名/画幅自动识别为 VR 素材（按钮上加一个小圆点提示）。 */
+  vr360Detected?: boolean
+  onToggleVr360?: () => void
   /** Media metadata duration (seconds). Used when HLS only knows transcoded length. */
   knownDuration?: number
   /** Absolute source offset of the current HLS session (seconds). */
@@ -159,6 +166,9 @@ export function PlayerControls({
   selectedQuality = '',
   onSelectQuality,
   showQuality = false,
+  vr360 = null,
+  vr360Detected = false,
+  onToggleVr360,
   knownDuration = 0,
   streamOffset = 0,
   onSeekAbsolute,
@@ -1090,6 +1100,24 @@ export function PlayerControls({
           {danmakuEnabled && <span className="h-1.5 w-1.5 rounded-full bg-lime-400" />}
         </button>
 
+        {/* VR 全景播放开关 */}
+        {onToggleVr360 && (
+          <button
+            onClick={onToggleVr360}
+            className={
+              'flex items-center gap-1.5 rounded-full px-2.5 py-1.5 text-xs font-medium transition ' +
+              (vr360
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/80 hover:bg-white/20')
+            }
+            title={vr360 ? '退出 VR 全景播放' : '切换到 VR 全景播放（可用鼠标或陀螺仪转动视角）'}
+          >
+            <Rotate3d size={15} />
+            <span className="hidden sm:inline">VR</span>
+            {vr360Detected && !vr360 && <span className="h-1.5 w-1.5 rounded-full bg-amber-300" />}
+          </button>
+        )}
+
         <button
           onClick={toggleMute}
           className="rounded-full p-1.5 transition hover:bg-white/15"

web/src/components/Vr360Stage.tsx

@@ -0,0 +1,613 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react'
+import { Check, Compass, Minus, Plus, RotateCcw, Settings2, Smartphone } from 'lucide-react'
+
+import {
+  VR360_DEFAULT_FOV,
+  VR360_MAX_FOV,
+  VR360_MIN_FOV,
+  VR360_PROJECTION_OPTIONS,
+  VR360_STEREO_OPTIONS,
+  vr360FrameUv,
+  type Vr360Profile,
+} from '../utils/vr360'
+import {
+  applyViewOffset,
+  cameraForward,
+  cameraFromDeviceOrientation,
+  cameraFromYawPitch,
+  clampNumber,
+  degToRad,
+  forwardPitch,
+  forwardYaw,
+  viewMatrixFromCamera,
+  type Mat3,
+} from '../utils/vr360Math'
+// 只引入类型：渲染器本体走动态 import，普通播放不会下载 WebGL 全景渲染代码。
+import type { Vr360Renderer } from '../utils/vr360Renderer'
+
+// 全景播放舞台：一个覆盖整个播放区域的 WebGL 画布。视频元素本身仍在后台正常
+// 播放（音轨、进度、弹幕、字幕都不受影响），只是画面被贴到了球面上。
+//
+// 视角控制：
+//   1. 鼠标/手指拖拽 → 转动视角（画面跟随手指），滚轮/双指捏合 → 变焦；
+//   2. 手机陀螺仪 → 转动设备即转动视角。iOS 13+ 必须在用户手势里调用
+//      DeviceOrientationEvent.requestPermission，所以这里做成显式按钮。
+
+type ViewState = {
+  /** 拖拽模式下的方位角（弧度，0 = 默认正前方）。 */
+  yaw: number
+  /** 拖拽模式下的俯仰角（弧度，+ 为抬头）。 */
+  pitch: number
+  fov: number
+  /** 陀螺仪是否接管视角。 */
+  gyroActive: boolean
+  /** 最近一次设备姿态对应的相机旋转矩阵。 */
+  deviceCamera: Mat3 | null
+  gyroYawOffset: number
+  gyroPitchOffset: number
+}
+
+type PointerState = {
+  x: number
+  y: number
+  startX: number
+  startY: number
+  startAt: number
+  moved: boolean
+}
+
+type GyroState = 'off' | 'pending' | 'active' | 'denied' | 'unsupported' | 'unavailable'
+
+type Vr360StageProps = {
+  videoRef: RefObject<HTMLVideoElement>
+  profile: Vr360Profile
+  /** 控制栏是否可见：不可见时隐藏 VR 自身的浮层按钮。 */
+  uiVisible: boolean
+  /** 轻触画面（未发生拖拽）时回调，与普通播放一致：唤出控制栏或切换播放。 */
+  onSurfaceTap: () => void
+  onReady: () => void
+  onError: (message: string) => void
+  /** 用户调整投影方式/立体布局时回调，由播放页保存为下次进入的默认值。 */
+  onProfileChange?: (profile: Vr360Profile) => void
+}
+
+/** 每像素拖拽对应的转角（弧度）。视场角越小时画面越「拉近」，拖拽也应更细腻。 */
+const DRAG_RAD_PER_PIXEL = 0.0035
+const TAP_MAX_DISTANCE = 8
+const TAP_MAX_DURATION_MS = 400
+const GYRO_PROBE_MS = 1500
+const PITCH_LIMIT = Math.PI / 2 - 0.03
+const WHEEL_ZOOM_SPEED = 0.0015
+
+function screenOrientationAngle(): number {
+  if (
+    typeof screen !== 'undefined' &&
+    screen.orientation &&
+    typeof screen.orientation.angle === 'number'
+  ) {
+    return screen.orientation.angle
+  }
+  const legacy = (window as unknown as { orientation?: number }).orientation
+  return typeof legacy === 'number' ? legacy : 0
+}
+
+type DeviceOrientationEventConstructor = {
+  requestPermission?: () => Promise<'granted' | 'denied' | 'default'>
+}
+
+function gyroStateHint(state: GyroState): string {
+  if (state === 'active') return '陀螺仪已开启：转动设备即可改变视角'
+  if (state === 'pending') return '正在等待陀螺仪数据…'
+  if (state === 'denied') return '陀螺仪权限被拒绝，请在浏览器设置里允许「运动与方向」访问'
+  if (state === 'unavailable') return '没有收到陀螺仪数据，当前设备可能不支持'
+  if (state === 'unsupported') return '当前浏览器不支持陀螺仪'
+  return ''
+}
+
+export function Vr360Stage({
+  videoRef,
+  profile,
+  uiVisible,
+  onSurfaceTap,
+  onReady,
+  onError,
+  onProfileChange,
+}: Vr360StageProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const rendererRef = useRef<Vr360Renderer | null>(null)
+  const viewRef = useRef<ViewState>({
+    yaw: 0,
+    pitch: 0,
+    fov: VR360_DEFAULT_FOV,
+    gyroActive: false,
+    deviceCamera: null,
+    gyroYawOffset: 0,
+    gyroPitchOffset: 0,
+  })
+  const dirtyRef = useRef(true)
+  const readyRef = useRef(false)
+  const pointersRef = useRef(new Map<number, PointerState>())
+  const pinchDistanceRef = useRef<number | null>(null)
+  const alignmentRef = useRef<{ yaw: number; pitch: number } | null>(null)
+  const gyroProbeRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const absoluteSeenRef = useRef(false)
+  const profileRef = useRef(profile)
+  const [gyroState, setGyroState] = useState<GyroState>('off')
+  const [fovHint, setFovHint] = useState(VR360_DEFAULT_FOV)
+  const [settingsOpen, setSettingsOpen] = useState(false)
+
+  // 回调放进 ref：渲染器只在挂载时创建一次，不因父组件重渲染而重建。
+  const callbacksRef = useRef({ onSurfaceTap, onReady, onError })
+  useEffect(() => {
+    callbacksRef.current = { onSurfaceTap, onReady, onError }
+  }, [onSurfaceTap, onReady, onError])
+
+  const markDirty = useCallback(() => {
+    dirtyRef.current = true
+  }, [])
+
+  // 当前相机姿态：陀螺仪接管时以设备姿态为基准叠加拖拽偏移，否则纯拖拽角度。
+  const currentCamera = useCallback((): Mat3 => {
+    const view = viewRef.current
+    if (view.gyroActive && view.deviceCamera) {
+      return applyViewOffset(view.deviceCamera, view.gyroYawOffset, view.gyroPitchOffset)
+    }
+    return cameraFromYawPitch(view.yaw, view.pitch)
+  }, [])
+
+  const draw = useCallback(() => {
+    const renderer = rendererRef.current
+    if (!renderer) return
+    renderer.setView(viewMatrixFromCamera(currentCamera()))
+    renderer.setFov(viewRef.current.fov)
+    renderer.draw()
+    if (!readyRef.current) {
+      // 第一帧真正画出来之后才通知上层：渲染失败时上层会退出 VR 模式。
+      readyRef.current = true
+      callbacksRef.current.onReady()
+    }
+  }, [currentCamera])
+
+  const applyProfile = useCallback((renderer: Vr360Renderer, next: Vr360Profile) => {
+    renderer.setProjection(next.projection)
+    const { scale, offset } = vr360FrameUv(next.stereo)
+    renderer.setFrameUv(scale, offset)
+    dirtyRef.current = true
+  }, [])
+
+  // 创建渲染器（懒加载 WebGL 模块，普通播放不会下载全景渲染代码）。
+  useEffect(() => {
+    const canvas = canvasRef.current
+    const video = videoRef.current
+    if (!canvas || !video) return
+    let cancelled = false
+    let created: Vr360Renderer | null = null
+
+    void import('../utils/vr360Renderer')
+      .then((module) => {
+        if (cancelled) return
+        created = module.createVr360Renderer(canvas, video, {
+          onContextLost: () => callbacksRef.current.onError('VR 渲染上下文已丢失，已退出 VR 播放'),
+          onTextureError: () => callbacksRef.current.onError('无法读取视频画面用于 VR 渲染'),
+        })
+        if (!created) {
+          callbacksRef.current.onError('当前浏览器不支持 WebGL，无法使用 VR 播放')
+          return
+        }
+        rendererRef.current = created
+        const rect = canvas.getBoundingClientRect()
+        created.resize(rect.width, rect.height)
+        applyProfile(created, profileRef.current)
+      })
+      .catch(() => {
+        if (!cancelled) callbacksRef.current.onError('VR 渲染组件加载失败')
+      })
+
+    return () => {
+      cancelled = true
+      rendererRef.current = null
+      created?.dispose()
+    }
+  }, [applyProfile, videoRef])
+
+  // 投影方式/立体布局变化时重建网格与 UV 裁切。
+  useEffect(() => {
+    profileRef.current = profile
+    const renderer = rendererRef.current
+    if (renderer) applyProfile(renderer, profile)
+  }, [applyProfile, profile])
+
+  // 画布尺寸跟随舞台（窗口缩放、全屏切换、首次布局）。
+  // 观测父容器而不是画布自身：画布尺寸由 CSS 撑满父容器，观测自身会在
+  // 「设置绘制缓冲区分辨率 → 布局变化 → 再次触发观测」之间来回放大。
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+    const target = canvas.parentElement ?? canvas
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (!entry) return
+      rendererRef.current?.resize(entry.contentRect.width, entry.contentRect.height)
+      markDirty()
+    })
+    observer.observe(target)
+    const rect = target.getBoundingClientRect()
+    rendererRef.current?.resize(rect.width, rect.height)
+    return () => observer.disconnect()
+  }, [markDirty])
+
+  // 渲染循环：requestVideoFrameCallback 标记「有新画面」，rAF 按需绘制。
+  // 暂停且无输入时不出图，避免持续占用 GPU。
+  useEffect(() => {
+    let handle = 0
+    let cancelled = false
+    const video = videoRef.current as
+      | (HTMLVideoElement & { requestVideoFrameCallback?: (callback: () => void) => number })
+      | null
+
+    if (video && typeof video.requestVideoFrameCallback === 'function') {
+      const onVideoFrame = () => {
+        if (cancelled) return
+        dirtyRef.current = true
+        video.requestVideoFrameCallback?.(onVideoFrame)
+      }
+      video.requestVideoFrameCallback(onVideoFrame)
+    }
+
+    const tick = () => {
+      if (cancelled) return
+      handle = requestAnimationFrame(tick)
+      if (!dirtyRef.current) return
+      dirtyRef.current = false
+      draw()
+    }
+    handle = requestAnimationFrame(tick)
+    return () => {
+      cancelled = true
+      cancelAnimationFrame(handle)
+    }
+  }, [draw, videoRef])
+
+  // 设备姿态 → 相机姿态。第一帧有效数据到达时把视角对齐过去，避免画面跳动。
+  const handleOrientation = useCallback((event: DeviceOrientationEvent) => {
+    if (event.alpha === null && event.beta === null && event.gamma === null) return
+    if (event.type === 'deviceorientationabsolute') absoluteSeenRef.current = true
+    // 同时收到绝对与相对事件时以绝对朝向为准（方位角才有意义）。
+    else if (absoluteSeenRef.current) return
+
+    const camera = cameraFromDeviceOrientation(
+      degToRad(event.alpha ?? 0),
+      degToRad(event.beta ?? 0),
+      degToRad(event.gamma ?? 0),
+      degToRad(screenOrientationAngle()),
+    )
+    const view = viewRef.current
+    view.deviceCamera = camera
+
+    const alignment = alignmentRef.current
+    if (alignment) {
+      const forward = cameraForward(camera)
+      view.gyroYawOffset = alignment.yaw - forwardYaw(forward)
+      view.gyroPitchOffset = clampNumber(alignment.pitch - forwardPitch(forward), -1.2, 1.2)
+      alignmentRef.current = null
+      if (gyroProbeRef.current) {
+        clearTimeout(gyroProbeRef.current)
+        gyroProbeRef.current = null
+      }
+      setGyroState('active')
+    }
+
+    view.gyroActive = true
+    dirtyRef.current = true
+  }, [])
+
+  const stopGyro = useCallback(() => {
+    window.removeEventListener('deviceorientation', handleOrientation)
+    window.removeEventListener('deviceorientationabsolute', handleOrientation)
+    if (gyroProbeRef.current) {
+      clearTimeout(gyroProbeRef.current)
+      gyroProbeRef.current = null
+    }
+    alignmentRef.current = null
+    absoluteSeenRef.current = false
+  }, [handleOrientation])
+
+  const startGyro = useCallback(() => {
+    alignmentRef.current = { yaw: viewRef.current.yaw, pitch: viewRef.current.pitch }
+    absoluteSeenRef.current = false
+    window.addEventListener('deviceorientation', handleOrientation)
+    window.addEventListener('deviceorientationabsolute', handleOrientation)
+    // 桌面浏览器/无陀螺仪设备会一直收不到事件，超时后提示并回退到拖拽模式。
+    gyroProbeRef.current = setTimeout(() => {
+      gyroProbeRef.current = null
+      if (alignmentRef.current) {
+        stopGyro()
+        setGyroState('unavailable')
+      }
+    }, GYRO_PROBE_MS)
+  }, [handleOrientation, stopGyro])
+
+  const toggleGyro = useCallback(() => {
+    if (gyroState === 'active' || gyroState === 'pending') {
+      // 关闭陀螺仪时用当前合成视角续上，画面不会跳。
+      const forward = cameraForward(currentCamera())
+      viewRef.current.yaw = forwardYaw(forward)
+      viewRef.current.pitch = clampNumber(forwardPitch(forward), -PITCH_LIMIT, PITCH_LIMIT)
+      viewRef.current.gyroActive = false
+      viewRef.current.gyroYawOffset = 0
+      viewRef.current.gyroPitchOffset = 0
+      stopGyro()
+      setGyroState('off')
+      markDirty()
+      return
+    }
+
+    const orientationEvent = (
+      window as unknown as { DeviceOrientationEvent?: DeviceOrientationEventConstructor }
+    ).DeviceOrientationEvent
+    if (!orientationEvent) {
+      setGyroState('unsupported')
+      return
+    }
+    setGyroState('pending')
+    const requestPermission = orientationEvent.requestPermission
+    if (typeof requestPermission !== 'function') {
+      startGyro()
+      return
+    }
+    // iOS 13+ 必须在用户手势里申请权限，这里由按钮点击直接触发。
+    void requestPermission
+      .call(orientationEvent)
+      .then((result) => {
+        if (result === 'granted') startGyro()
+        else setGyroState('denied')
+      })
+      .catch(() => setGyroState('denied'))
+  }, [currentCamera, gyroState, markDirty, startGyro, stopGyro])
+
+  useEffect(() => () => stopGyro(), [stopGyro])
+
+  const zoomBy = useCallback(
+    (factor: number) => {
+      const view = viewRef.current
+      view.fov = clampNumber(view.fov * factor, VR360_MIN_FOV, VR360_MAX_FOV)
+      setFovHint(view.fov)
+      markDirty()
+    },
+    [markDirty],
+  )
+
+  const resetView = useCallback(() => {
+    const view = viewRef.current
+    view.yaw = 0
+    view.pitch = 0
+    view.fov = VR360_DEFAULT_FOV
+    view.gyroYawOffset = 0
+    view.gyroPitchOffset = 0
+    setFovHint(view.fov)
+    markDirty()
+  }, [markDirty])
+
+  const pinchDistance = useCallback((): number => {
+    const pointers = [...pointersRef.current.values()]
+    if (pointers.length < 2) return 0
+    return Math.hypot(pointers[0].x - pointers[1].x, pointers[0].y - pointers[1].y)
+  }, [])
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    try {
+      event.currentTarget.setPointerCapture?.(event.pointerId)
+    } catch {
+      // 某些环境（合成事件、非活跃指针）会抛 InvalidPointerId，退化为普通拖拽即可。
+    }
+    pointersRef.current.set(event.pointerId, {
+      x: event.clientX,
+      y: event.clientY,
+      startX: event.clientX,
+      startY: event.clientY,
+      startAt: Date.now(),
+      moved: false,
+    })
+    if (pointersRef.current.size === 2) {
+      pinchDistanceRef.current = pinchDistance()
+      // 双指手势一律不算轻触，避免捏合缩放时误触发播放/暂停。
+      for (const pointer of pointersRef.current.values()) pointer.moved = true
+    }
+  }
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    const pointer = pointersRef.current.get(event.pointerId)
+    if (!pointer) return
+    const dx = event.clientX - pointer.x
+    const dy = event.clientY - pointer.y
+    pointer.x = event.clientX
+    pointer.y = event.clientY
+    if (
+      Math.hypot(event.clientX - pointer.startX, event.clientY - pointer.startY) > TAP_MAX_DISTANCE
+    ) {
+      pointer.moved = true
+    }
+
+    if (pointersRef.current.size >= 2) {
+      const distance = pinchDistance()
+      const previous = pinchDistanceRef.current
+      pinchDistanceRef.current = distance
+      if (previous && distance > 0) zoomBy(previous / distance)
+      return
+    }
+
+    const view = viewRef.current
+    const scale = DRAG_RAD_PER_PIXEL * (view.fov / VR360_DEFAULT_FOV)
+    if (view.gyroActive && view.deviceCamera) {
+      view.gyroYawOffset -= dx * scale
+      view.gyroPitchOffset = clampNumber(
+        view.gyroPitchOffset + dy * scale,
+        -PITCH_LIMIT,
+        PITCH_LIMIT,
+      )
+    } else {
+      view.yaw -= dx * scale
+      view.pitch = clampNumber(view.pitch + dy * scale, -PITCH_LIMIT, PITCH_LIMIT)
+    }
+    markDirty()
+  }
+
+  const endPointer = (event: ReactPointerEvent<HTMLCanvasElement>) => {
+    const pointer = pointersRef.current.get(event.pointerId)
+    pointersRef.current.delete(event.pointerId)
+    if (pointersRef.current.size < 2) pinchDistanceRef.current = null
+    if (!pointer) return
+    const isTap =
+      !pointer.moved &&
+      Date.now() - pointer.startAt <= TAP_MAX_DURATION_MS &&
+      pointersRef.current.size === 0
+    if (isTap) onSurfaceTap()
+  }
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+    const onWheel = (event: WheelEvent) => {
+      event.preventDefault()
+      zoomBy(1 + event.deltaY * WHEEL_ZOOM_SPEED)
+    }
+    canvas.addEventListener('wheel', onWheel, { passive: false })
+    return () => canvas.removeEventListener('wheel', onWheel)
+  }, [zoomBy])
+
+  const hint = gyroStateHint(gyroState)
+
+  return (
+    <>
+      <canvas
+        ref={canvasRef}
+        data-vr360-surface
+        className="absolute inset-0 h-full w-full cursor-grab touch-none select-none active:cursor-grabbing"
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={endPointer}
+        onPointerCancel={endPointer}
+        // 轻触由指针逻辑自己处理（拖动时不能误触发播放/暂停），
+        // 同时阻止冒泡到舞台的点击逻辑，避免一次触摸切换两次播放状态。
+        onClick={(event) => event.stopPropagation()}
+      />
+      <div
+        className={`pointer-events-none absolute inset-x-0 top-2 z-20 flex flex-col items-center gap-1.5 px-2 transition-opacity duration-300 ${
+          uiVisible ? 'opacity-100' : 'opacity-0'
+        }`}
+      >
+        <div className="pointer-events-auto flex flex-wrap items-center justify-center gap-1.5 rounded-2xl border border-white/15 bg-black/65 px-2 py-1.5 text-white shadow-2xl backdrop-blur">
+          <button
+            type="button"
+            onClick={toggleGyro}
+            className={`flex items-center gap-1.5 rounded-full px-2.5 py-1 text-xs font-medium transition ${
+              gyroState === 'active'
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/85 hover:bg-white/20'
+            }`}
+            title="用手机陀螺仪转动视角"
+          >
+            <Smartphone size={14} />
+            陀螺仪
+            {gyroState === 'active' && <Compass size={13} className="text-white/85" />}
+          </button>
+          <button
+            type="button"
+            onClick={resetView}
+            className="flex items-center gap-1.5 rounded-full bg-white/10 px-2.5 py-1 text-xs font-medium text-white/85 transition hover:bg-white/20"
+            title="恢复默认视角与视场角"
+          >
+            <RotateCcw size={14} />
+            重置
+          </button>
+          <button
+            type="button"
+            onClick={() => setSettingsOpen((open) => !open)}
+            className={`flex items-center gap-1.5 rounded-full px-2.5 py-1 text-xs font-medium transition ${
+              settingsOpen
+                ? 'bg-rose-500/90 text-white hover:bg-rose-500'
+                : 'bg-white/10 text-white/85 hover:bg-white/20'
+            }`}
+            title="投影方式与画幅布局"
+          >
+            <Settings2 size={14} />
+            画面
+          </button>
+          <div className="flex items-center gap-0.5">
+            <button
+              type="button"
+              onClick={() => zoomBy(1.15)}
+              className="rounded-full p-1.5 transition hover:bg-white/15"
+              title="视野拉远"
+            >
+              <Minus size={15} />
+            </button>
+            <span className="w-9 text-center text-[10px] tabular-nums text-white/75">
+              {(VR360_DEFAULT_FOV / fovHint).toFixed(1)}×
+            </span>
+            <button
+              type="button"
+              onClick={() => zoomBy(1 / 1.15)}
+              className="rounded-full p-1.5 transition hover:bg-white/15"
+              title="视野拉近"
+            >
+              <Plus size={15} />
+            </button>
+          </div>
+        </div>
+        <p className="pointer-events-none rounded-full bg-black/45 px-3 py-1 text-[10px] text-white/70 backdrop-blur">
+          {hint || '拖动旋转视角 · 滚轮或双指缩放'}
+        </p>
+        {settingsOpen ? (
+          <div className="pointer-events-auto w-[min(92vw,420px)] rounded-2xl border border-white/15 bg-black/75 px-3 py-2.5 text-white shadow-2xl backdrop-blur">
+            <p className="mb-1.5 text-[10px] uppercase tracking-wide text-white/45">投影方式</p>
+            <div className="flex flex-wrap gap-1.5">
+              {VR360_PROJECTION_OPTIONS.map(([value, label]) => (
+                <button
+                  key={value}
+                  type="button"
+                  onClick={() => onProfileChange?.({ ...profile, projection: value })}
+                  className={`flex items-center gap-1 rounded-lg px-2.5 py-1 text-[11px] transition ${
+                    profile.projection === value
+                      ? 'bg-rose-500/25 text-rose-200'
+                      : 'bg-white/5 text-white/75 hover:bg-white/15'
+                  }`}
+                >
+                  {profile.projection === value && <Check size={11} />}
+                  {label}
+                </button>
+              ))}
+            </div>
+            <p className="mb-1.5 mt-2.5 text-[10px] uppercase tracking-wide text-white/45">
+              画幅布局
+            </p>
+            <div className="flex flex-wrap gap-1.5">
+              {VR360_STEREO_OPTIONS.map(([value, label]) => (
+                <button
+                  key={value}
+                  type="button"
+                  onClick={() => onProfileChange?.({ ...profile, stereo: value })}
+                  className={`flex items-center gap-1 rounded-lg px-2.5 py-1 text-[11px] transition ${
+                    profile.stereo === value
+                      ? 'bg-rose-500/25 text-rose-200'
+                      : 'bg-white/5 text-white/75 hover:bg-white/15'
+                  }`}
+                >
+                  {profile.stereo === value && <Check size={11} />}
+                  {label}
+                </button>
+              ))}
+            </div>
+            {profile.stereo !== 'mono' && (
+              <p className="mt-2 text-[10px] leading-relaxed text-white/45">
+                左右/上下并排素材在当前屏幕上只显示左眼画面；真正的双眼立体画面需要 VR
+                头显（WebXR）。
+              </p>
+            )}
+          </div>
+        ) : null}
+      </div>
+    </>
+  )
+}

web/src/pages/PlayerPage.tsx

@@ -42,6 +42,13 @@ import { PlayerDanmakuPanel } from '../components/PlayerDanmakuPanel'
 import { PlayerPlaylistPanel } from '../components/PlayerPlaylistPanel'
 import { MediaVersionSwitcher } from '../components/MediaVersionSwitcher'
 import { mediaVersionsOf } from '../utils/mediaVersion'
+import {
+  detectVr360Profile,
+  loadVr360Preference,
+  saveVr360Preference,
+  type Vr360Detection,
+  type Vr360Profile,
+} from '../utils/vr360'
 
 // Fullscreen, dark-themed video page.
 //
@@ -96,6 +103,11 @@ export function PlayerPage() {
   const fallbackTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const [media, setMedia] = useState<Media | null>(null)
+  // VR 全景播放：null = 普通播放。识别结果与用户开关只存本机，
+  // 不改动数据库，换设备/换浏览器不会互相影响。
+  const [vr360, setVr360] = useState<Vr360Profile | null>(null)
+  const [vr360Detected, setVr360Detected] = useState(false)
+  const vr360TouchedRef = useRef(false)
   const [mode, setMode] = useState<PlayerMode>('direct')
   const [subs, setSubs] = useState<SubtitleTrack[]>([])
   const [subtitleIndex, setSubtitleIndex] = useState<number>(0)
@@ -458,6 +470,9 @@ export function PlayerPage() {
   useEffect(() => {
     setMedia(null)
     setLoadError('')
+    vr360TouchedRef.current = false
+    setVr360(null)
+    setVr360Detected(false)
     setHlsStartSec(0)
     setPlaybackInfo(null)
     setHlsSource('local')
@@ -537,6 +552,68 @@ export function PlayerPage() {
     }
   }, [id, modeParam, directOnly])
 
+  // VR 全景素材识别：只在用户没手动改过开关时自动进入 VR 模式。
+  // 识别完全基于文件名/路径关键词与画幅比例，误判时点一下 VR 按钮即可退出。
+  useEffect(() => {
+    if (!media || media.id !== id) return
+    const detection = detectVr360Profile({
+      title: media.title,
+      originalName: media.original_name,
+      path: media.path,
+      relativePath: media.relative_path,
+      width: media.width,
+      height: media.height,
+    })
+    setVr360Detected(detection.confident)
+    if (vr360TouchedRef.current) return
+    const preference = loadVr360Preference()
+    if (!preference.autoDetect || !detection.confident) {
+      setVr360(null)
+      return
+    }
+    if (detection.profile.projection !== preference.profile.projection) {
+      // 投影方式由文件名决定（360 / 180 / 鱼眼），记住它作为下次的默认值。
+      saveVr360Preference({ ...preference, profile: detection.profile })
+    }
+    setVr360(detection.profile)
+  }, [id, media])
+
+  const toggleVr360 = useCallback(() => {
+    vr360TouchedRef.current = true
+    if (vr360) {
+      setVr360(null)
+      return
+    }
+    const current = mediaRef.current
+    const detection: Vr360Detection | null = current
+      ? detectVr360Profile({
+          title: current.title,
+          originalName: current.original_name,
+          path: current.path,
+          relativePath: current.relative_path,
+          width: current.width,
+          height: current.height,
+        })
+      : null
+    const preference = loadVr360Preference()
+    const profile = detection?.profile ?? preference.profile
+    saveVr360Preference({ ...preference, profile })
+    setVr360(profile)
+  }, [vr360])
+
+  const changeVr360Profile = useCallback((profile: Vr360Profile) => {
+    vr360TouchedRef.current = true
+    setVr360(profile)
+    saveVr360Preference({ ...loadVr360Preference(), profile })
+  }, [])
+
+  const handleVr360Error = useCallback((message: string) => {
+    vr360TouchedRef.current = true
+    setVr360(null)
+    setPlayerError(message)
+    toast.error(message)
+  }, [])
+
   // Wire up the actual <video> element when we know the mode.
   // Depend on media.id (not the media object): refreshing duration after
   // MANIFEST_PARSED must not remount HLS or it storms EnsureJob / DELETE.
@@ -1499,6 +1576,11 @@ export function PlayerPage() {
         showQuality={showQuality}
         waiting={cloudWaiting}
         waitingMessage={cloudWaitMessage}
+        vr360={vr360}
+        vr360Detected={vr360Detected}
+        onToggleVr360={toggleVr360}
+        onVr360ProfileChange={changeVr360Profile}
+        onVr360Error={handleVr360Error}
         playlistPanel={
           <PlayerPlaylistPanel
             open={playlistOpen}

web/src/pages/PlayerVideoStage.tsx

@@ -12,6 +12,8 @@ import {
 import { AssSubtitleStage } from '../components/AssSubtitleStage'
 import { DanmakuStage } from '../components/DanmakuStage'
 import { PlayerControls } from '../components/PlayerControls'
+import { Vr360Stage } from '../components/Vr360Stage'
+import type { Vr360Profile } from '../utils/vr360'
 import {
   subtitleTextStyle,
   type SubtitlePosition,
@@ -186,6 +188,13 @@ type PlayerVideoStageProps = {
   selectedQuality?: string
   onSelectQuality?: (quality: PlaybackQuality) => void
   showQuality?: boolean
+  /** VR 全景播放配置；非 null 表示当前处于 VR 模式。 */
+  vr360?: Vr360Profile | null
+  /** 是否由文件名/画幅自动识别出 VR 素材（用于在菜单里提示）。 */
+  vr360Detected?: boolean
+  onToggleVr360?: () => void
+  onVr360ProfileChange?: (profile: Vr360Profile) => void
+  onVr360Error?: (message: string) => void
   waiting?: boolean
   waitingMessage?: string
 }
@@ -241,6 +250,11 @@ export function PlayerVideoStage({
   selectedQuality = '',
   onSelectQuality,
   showQuality = false,
+  vr360 = null,
+  vr360Detected = false,
+  onToggleVr360,
+  onVr360ProfileChange,
+  onVr360Error,
   waiting = false,
   waitingMessage = '',
 }: PlayerVideoStageProps) {
@@ -248,6 +262,8 @@ export function PlayerVideoStage({
   const [videoRatio, setVideoRatio] = useState<number | null>(null)
   const [stageRect, setStageRect] = useState<{ width: number; height: number } | null>(null)
   const [controlsVisible, setControlsVisible] = useState(true)
+  // VR 渲染器是否已经画出第一帧（在此之前给出「正在启动」提示，避免只看到黑屏）。
+  const [vrReady, setVrReady] = useState(false)
   const revealControlsOnlyRef = useRef(false)
   // 当前展示的字幕文本（由自定义字幕层渲染，100% 透明无黑框）
   const [activeCues, setActiveCues] = useState<SubtitleCue[]>([])
@@ -270,6 +286,11 @@ export function PlayerVideoStage({
     setAssFallbackPath(null)
   }, [media?.id, activeSubtitleTrack?.path, subs])
 
+  // 切换媒体或 VR 配置后重新等待渲染器的第一帧。
+  useEffect(() => {
+    setVrReady(false)
+  }, [media?.id, vr360?.projection, vr360?.stereo])
+
   useEffect(() => {
     const selectedTrack = subs[subtitleIndex]
     let cancelled = false
@@ -392,7 +413,9 @@ export function PlayerVideoStage({
   const handleStagePointerDown = (event: PointerEvent<HTMLDivElement>) => {
     revealControlsOnlyRef.current = event.pointerType === 'touch' && !controlsVisible
   }
-  const handleStageClick = () => {
+  // 舞台任意位置的「激活」（轻触/单击）：移动端控制栏隐藏时首次轻触只唤出
+  // 控制栏，控制栏已显示时再次轻触才切换播放/暂停。
+  const handleSurfaceActivate = () => {
     if (revealControlsOnlyRef.current) {
       revealControlsOnlyRef.current = false
       setControlsVisible(true)
@@ -550,18 +573,25 @@ export function PlayerVideoStage({
       : true
 
   const assTrack = subtitleIndex >= 0 ? subs[subtitleIndex] : undefined
-  const wrapperStyle = videoRatio
+  // VR 模式下画面由 WebGL 画布输出，舞台窗口本身就是「镜头」，
+  // 不再按视频宽高比留黑边。
+  const wrapperStyle = vr360
     ? {
-        aspectRatio: `${videoRatio}`,
-        width: isWiderThanStage ? '100%' : 'auto',
-        height: isWiderThanStage ? 'auto' : '100%',
-        maxWidth: '100%',
-        maxHeight: '100%',
-      }
-    : {
         width: '100%',
         height: '100%',
       }
+    : videoRatio
+      ? {
+          aspectRatio: `${videoRatio}`,
+          width: isWiderThanStage ? '100%' : 'auto',
+          height: isWiderThanStage ? 'auto' : '100%',
+          maxWidth: '100%',
+          maxHeight: '100%',
+        }
+      : {
+          width: '100%',
+          height: '100%',
+        }
 
   return (
     <div
@@ -569,7 +599,7 @@ export function PlayerVideoStage({
       data-player-stage
       className="relative flex h-full w-full flex-1 items-center justify-center overflow-hidden bg-black"
       onPointerDown={handleStagePointerDown}
-      onClick={handleStageClick}
+      onClick={handleSurfaceActivate}
       onDoubleClick={toggleFullscreen}
     >
       {media ? (
@@ -602,6 +632,18 @@ export function PlayerVideoStage({
                   )
                 })}
             </video>
+            {vr360 ? (
+              <Vr360Stage
+                key={`${media.id}:vr360`}
+                videoRef={videoRef}
+                profile={vr360}
+                uiVisible={controlsVisible}
+                onSurfaceTap={handleSurfaceActivate}
+                onReady={() => setVrReady(true)}
+                onError={(message) => onVr360Error?.(message)}
+                onProfileChange={onVr360ProfileChange}
+              />
+            ) : null}
             <DanmakuStage
               key={media.id}
               media={media}
@@ -692,6 +734,9 @@ export function PlayerVideoStage({
             selectedQuality={selectedQuality}
             onSelectQuality={onSelectQuality}
             showQuality={showQuality}
+            vr360={vr360}
+            vr360Detected={vr360Detected}
+            onToggleVr360={onToggleVr360}
           />
           {danmakuPanel}
           {playlistPanel}
@@ -701,6 +746,14 @@ export function PlayerVideoStage({
       ) : (
         <p className="text-sand-500">加载中…</p>
       )}
+      {vr360 && media && !vrReady ? (
+        <div className="pointer-events-none absolute inset-0 z-30 flex items-center justify-center bg-black/60">
+          <div className="flex items-center gap-2 rounded-full border border-white/15 bg-black/80 px-5 py-3 text-sm text-white shadow-2xl backdrop-blur">
+            <Loader2 className="animate-spin text-rose-400" size={18} />
+            正在启动 VR 全景渲染…
+          </div>
+        </div>
+      ) : null}
       {playerError ? (
         <div className="absolute bottom-20 left-1/2 w-[min(92vw,720px)] -translate-x-1/2 rounded-2xl border border-white/15 bg-black/75 px-5 py-4 text-sm text-white shadow-2xl backdrop-blur">
           {playerError}

web/src/utils/mediaVersion.test.ts

@@ -0,0 +1,44 @@
+import { mediaVersionLabel } from './mediaVersion.ts'
+import type { Media } from '../types/index.ts'
+
+function check(name: string, condition: boolean) {
+  if (!condition) throw new Error(`mediaVersion: ${name}`)
+}
+
+function media(partial: Partial<Media>): Media {
+  return {
+    id: 'm1',
+    title: 'SIVR-270',
+    path: '',
+    height: 0,
+    width: 0,
+    size_bytes: 0,
+    ...partial,
+  } as Media
+}
+
+const partLabel = mediaVersionLabel(media({
+  path: '/media/云下载/sivr-270/sivr-270-1.strm',
+  size_bytes: 157,
+  strm_url: '/api/strm/play/cloud115/video.mp4?pickcode=a',
+}))
+check('indistinct strm falls back to filename', partLabel.includes('sivr-270-1'))
+check('indistinct strm is not generic MP4 only', partLabel.toUpperCase() !== 'MP4')
+
+const richLabel = mediaVersionLabel(media({
+  path: '/strm/竞女01.mkv.strm',
+  height: 1080,
+  size_bytes: 1024 * 1024 * 1200,
+  strm_url: '/api/strm/play/cloud115/video.mkv?pickcode=a',
+}))
+check('rich metadata keeps resolution label', richLabel.includes('1080p'))
+check('rich metadata keeps container', richLabel.toUpperCase().includes('MKV'))
+
+const dottedPart = mediaVersionLabel(media({
+  path: '/media/云下载/ipvr00192pl/fbzip.com@ipvr00192.part2.strm',
+  size_bytes: 157,
+  strm_url: '/api/strm/play/cloud115/video.mp4?pickcode=b',
+}))
+check('part2 filename fallback keeps part token', dottedPart.includes('part2'))
+
+console.log('mediaVersion.test.ts: ok')

web/src/utils/mediaVersion.ts

@@ -107,6 +107,15 @@ function cleanFallbackFilename(raw: string): string {
   return name
 }
 
+function isIndistinctVersionLabel(parts: string[]): boolean {
+  if (parts.length === 0) return true
+  return parts.every((part) => {
+    const upper = part.toUpperCase()
+    if (upper === '云端直链' || upper === 'STRM') return true
+    return VIDEO_EXTENSIONS.has(part.toLowerCase())
+  })
+}
+
 /** 版本切换展示名：分辨率 · 容器 · 编码 · 体积 / 规格 / 来源标签。 */
 export function mediaVersionLabel(media: Media): string {
   const isStrm = isStrmMedia(media)
@@ -153,11 +162,11 @@ export function mediaVersionLabel(media: Media): string {
     parts.push('云端直链')
   }
 
-  if (parts.length > 0) {
+  // 只有容器 /「云端直链」时无法区分多分片，回退文件名（sivr-270-1 / …part1）
+  if (parts.length > 0 && !isIndistinctVersionLabel(parts)) {
     return parts.join(' · ')
   }
 
-  // 兜底：使用清理后的文件名
   const cleaned = cleanFallbackFilename(media.path || '')
   return cleaned || media.title || media.id
 }

web/src/utils/vr360.test.ts

@@ -0,0 +1,162 @@
+import {
+  detectVr360Profile,
+  normalizeVr360Profile,
+  sameVr360Profile,
+  vr360FrameUv,
+  type Vr360Profile,
+} from './vr360.ts'
+import {
+  applyDirection,
+  applyViewOffset,
+  cameraForward,
+  cameraFromDeviceOrientation,
+  cameraFromYawPitch,
+  forwardPitch,
+  forwardYaw,
+  multiply3,
+  perspectiveMatrix,
+  rotationY,
+  rotationZ,
+  transpose3,
+  viewMatrixFromCamera,
+} from './vr360Math.ts'
+
+function check(name: string, condition: boolean) {
+  if (!condition) throw new Error(`vr360: ${name}`)
+}
+
+function close(a: number, b: number, tolerance = 1e-6): boolean {
+  return Math.abs(a - b) <= tolerance
+}
+
+function closeAll(a: number[], b: number[], tolerance = 1e-6): boolean {
+  return a.length === b.length && a.every((value, index) => close(value, b[index], tolerance))
+}
+
+function profileOf(profile: Vr360Profile): string {
+  return `${profile.projection}/${profile.stereo}`
+}
+
+// ---------- 命名/画幅识别 ----------
+
+const plain = detectVr360Profile({ title: '普通电影', path: '/media/电影/movie.mkv', width: 1920, height: 1080 })
+check('普通素材不自动进入 VR', !plain.confident)
+check('普通素材默认 360 单眼', profileOf(plain.profile) === 'equirect360/mono')
+
+const pano360 = detectVr360Profile({
+  title: '全景演示',
+  path: '/media/360/equirect_demo.mp4',
+  width: 3840,
+  height: 1920,
+})
+check('360 关键词可识别', pano360.confident && pano360.profile.projection === 'equirect360')
+check('2:1 的 360 保持单眼', pano360.profile.stereo === 'mono')
+
+const vr360Sbs = detectVr360Profile({ path: '/media/vr/vr360-sbs-8k.mp4', width: 7680, height: 1920 })
+check('4:1 画幅识别为左右并排', vr360Sbs.profile.stereo === 'sbs')
+
+const ou360 = detectVr360Profile({ path: '/media/vr/pano360-ou.mp4', width: 3840, height: 3840 })
+check('1:1 的 360 识别为上下并排', ou360.profile.stereo === 'ou')
+
+const fisheye = detectVr360Profile({ path: '/media/vr/abc-fisheye-180.mp4', width: 1920, height: 1920 })
+check('鱼眼关键词优先于其它信号', fisheye.profile.projection === 'fisheye180')
+
+const vr180Sbs = detectVr360Profile({
+  path: '/media/云下载/sivr-270/sivr-270-1.mp4',
+  width: 3840,
+  height: 1920,
+})
+check('编号里的 vr 可识别为 VR180', vr180Sbs.confident && vr180Sbs.profile.projection === 'equirect180')
+check('VR180 的 2:1 画幅为左右并排', vr180Sbs.profile.stereo === 'sbs')
+
+const vr180Mono = detectVr360Profile({ path: '/media/vr/vr180-mono.mp4', width: 1920, height: 1920 })
+check('VR180 的 1:1 画幅为单眼', vr180Mono.profile.stereo === 'mono')
+
+const vr180Ou = detectVr360Profile({ path: '/media/vr/vr180-tb.mp4', width: 1920, height: 3840 })
+check('VR180 的 1:2 画幅为上下并排', vr180Ou.profile.stereo === 'ou')
+
+const topBottom = detectVr360Profile({ path: '/media/vr/vr360-top-bottom.mp4' })
+check('top-bottom 关键词为上下并排', topBottom.profile.stereo === 'ou')
+
+// ---------- 立体裁切与偏好归一化 ----------
+
+check('单眼不裁切', closeAll(vr360FrameUv('mono').scale, [1, 1]))
+check('左右并排取左半张', closeAll(vr360FrameUv('sbs').scale, [0.5, 1]))
+check('上下并排取上半张', closeAll(vr360FrameUv('ou').scale, [1, 0.5]))
+check('并排画面不做偏移', closeAll(vr360FrameUv('sbs').offset, [0, 0]))
+
+check('未知投影回退到 360 全景', normalizeVr360Profile({ projection: 'nope', stereo: 'nope' }).projection === 'equirect360')
+check('未知布局回退到单眼', normalizeVr360Profile({}).stereo === 'mono')
+check(
+  '相同配置判定相等',
+  sameVr360Profile({ projection: 'equirect180', stereo: 'sbs' }, { projection: 'equirect180', stereo: 'sbs' }),
+)
+check(
+  '不同配置判定不等',
+  !sameVr360Profile({ projection: 'equirect180', stereo: 'sbs' }, { projection: 'equirect180', stereo: 'ou' }),
+)
+
+// ---------- 相机姿态与设备陀螺仪 ----------
+
+const identityForward = cameraForward(new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1]))
+check('单位姿态朝向地面（设备平放）', closeAll([...identityForward], [0, 0, -1]))
+
+const level = cameraFromYawPitch(0, 0)
+check('默认视角水平看向正前方', closeAll([...cameraForward(level)], [0, 1, 0]))
+
+const east = cameraFromYawPitch(Math.PI / 2, 0)
+check('方位角 90° 转向正东', closeAll([...cameraForward(east)], [1, 0, 0], 1e-6))
+
+const up = cameraFromYawPitch(0, Math.PI / 2)
+check('俯仰角 90° 抬头看天', closeAll([...cameraForward(up)], [0, 0, 1], 1e-6))
+
+const northEast = cameraFromYawPitch(Math.PI / 4, 0)
+check('方位角 45° 落在东北方向', close(forwardYaw(cameraForward(northEast)), Math.PI / 4))
+
+const tilted = cameraFromYawPitch(0.3, -0.4)
+check('朝向角可反解出方位角', close(forwardYaw(cameraForward(tilted)), 0.3, 1e-6))
+check('朝向角可反解出俯仰角', close(forwardPitch(cameraForward(tilted)), -0.4, 1e-6))
+
+check(
+  '旋转矩阵转置等于反向旋转',
+  closeAll([...transpose3(rotationY(0.7))], [...rotationY(-0.7)], 1e-6),
+)
+check(
+  '正反旋转相乘为单位矩阵',
+  closeAll(
+    [...multiply3(rotationZ(1.1), rotationZ(-1.1))],
+    [1, 0, 0, 0, 1, 0, 0, 0, 1],
+    1e-6,
+  ),
+)
+
+// 视图矩阵 = 相机姿态的逆（纯旋转）
+const view = viewMatrixFromCamera(east)
+check('视图矩阵为相机矩阵的转置', closeAll([...view], [...transpose3(east)], 1e-6))
+
+// 设备姿态约定（与 W3C 规范一致）：相机看向设备背面，
+// 因此设备平放时（alpha 任意、beta = 0）视线朝下。
+const flat = cameraFromDeviceOrientation(Math.PI / 3, 0, 0, 0)
+check('设备平放时看向地面', closeAll([...cameraForward(flat)], [0, 0, -1], 1e-6))
+
+// 竖持手机（beta = 90°）时视线水平
+const portrait = cameraFromDeviceOrientation(0, Math.PI / 2, 0, 0)
+check('竖持手机时视线水平', close(cameraForward(portrait)[2], 0, 1e-6))
+check('竖持手机时视线朝北', close(forwardYaw(cameraForward(portrait)), 0, 1e-6))
+
+// 横屏（屏幕旋转 90°）时相机「上方向」跟随屏幕
+const landscape = cameraFromDeviceOrientation(0, Math.PI / 2, 0, Math.PI / 2)
+check('横屏时画面随屏幕转向', closeAll([...applyDirection(landscape, 0, 1, 0)], [1, 0, 0], 1e-6))
+
+// 陀螺仪开启瞬间的视角对齐：叠加偏移后朝向应等于对齐前记录的拖拽视角
+const aligned = applyViewOffset(cameraFromDeviceOrientation(0, Math.PI / 2, 0, 0), 0.5, 0.25)
+check('叠加偏移后方位角对齐', close(forwardYaw(cameraForward(aligned)), 0.5, 1e-6))
+check('叠加偏移后俯仰角对齐', close(forwardPitch(cameraForward(aligned)), 0.25, 1e-6))
+
+// ---------- 透视投影 ----------
+
+const projection = perspectiveMatrix(Math.PI / 2, 2, 0.1, 10)
+check('透视矩阵缩放项随视场角变化', close(projection[0], 0.5))
+check('透视矩阵写入 w = -1（右手系）', projection[11] === -1)
+
+console.log('vr360.test.ts: ok')

web/src/utils/vr360.ts

@@ -0,0 +1,229 @@
+// VR360（全景）播放的配置模型、命名启发式识别与本地偏好。
+//
+// 网页端只能从文件名/路径和画幅比例推断「这段视频是不是全景/VR」，任何信号
+// 都不绝对可靠，所以这里只负责给出「大概率正确」的初始配置：识别结果不写入
+// 数据库，用户随时可以在播放器菜单里改投影方式与立体布局，改动只影响本机。
+
+export type Vr360Projection = 'equirect360' | 'equirect180' | 'fisheye180'
+export type Vr360Stereo = 'mono' | 'sbs' | 'ou'
+
+export type Vr360Profile = {
+  /** 画面投影方式：360 等距柱状、180 等距柱状、180 鱼眼。 */
+  projection: Vr360Projection
+  /** 立体布局：单眼、左右并排、上下并排。 */
+  stereo: Vr360Stereo
+}
+
+export const DEFAULT_VR360_PROFILE: Vr360Profile = {
+  projection: 'equirect360',
+  stereo: 'mono',
+}
+
+/** 视场角可调范围（度）：数值越小画面越「拉近」。 */
+export const VR360_MIN_FOV = 35
+export const VR360_MAX_FOV = 110
+export const VR360_DEFAULT_FOV = 75
+
+export const VR360_PROJECTION_OPTIONS: Array<[Vr360Projection, string]> = [
+  ['equirect360', '360° 全景'],
+  ['equirect180', '180° 半景'],
+  ['fisheye180', '180° 鱼眼'],
+]
+
+export const VR360_STEREO_OPTIONS: Array<[Vr360Stereo, string]> = [
+  ['mono', '单眼'],
+  ['sbs', '左右并排'],
+  ['ou', '上下并排'],
+]
+
+export function vr360ProjectionLabel(projection: Vr360Projection): string {
+  return VR360_PROJECTION_OPTIONS.find(([value]) => value === projection)?.[1] ?? '360° 全景'
+}
+
+export function vr360StereoLabel(stereo: Vr360Stereo): string {
+  return VR360_STEREO_OPTIONS.find(([value]) => value === stereo)?.[1] ?? '单眼'
+}
+
+export function normalizeVr360Projection(value: unknown): Vr360Projection {
+  return value === 'equirect180' || value === 'fisheye180' ? value : 'equirect360'
+}
+
+export function normalizeVr360Stereo(value: unknown): Vr360Stereo {
+  return value === 'sbs' || value === 'ou' ? value : 'mono'
+}
+
+export function normalizeVr360Profile(value: unknown): Vr360Profile {
+  const profile = (value ?? {}) as Partial<Vr360Profile>
+  return {
+    projection: normalizeVr360Projection(profile.projection),
+    stereo: normalizeVr360Stereo(profile.stereo),
+  }
+}
+
+export function sameVr360Profile(a: Vr360Profile, b: Vr360Profile): boolean {
+  return a.projection === b.projection && a.stereo === b.stereo
+}
+
+// 立体素材（左右/上下并排）在普通屏幕上只取左眼画面：真正的双眼渲染需要
+// WebXR 头显，网页里把两半都画出来只会得到重复画面。
+export function vr360FrameUv(stereo: Vr360Stereo): {
+  scale: [number, number]
+  offset: [number, number]
+} {
+  if (stereo === 'sbs') return { scale: [0.5, 1], offset: [0, 0] }
+  if (stereo === 'ou') return { scale: [1, 0.5], offset: [0, 0] }
+  return { scale: [1, 1], offset: [0, 0] }
+}
+
+export type Vr360DetectInput = {
+  title?: string
+  originalName?: string
+  path?: string
+  relativePath?: string
+  /** 视频画面宽度（媒体元数据或 ffprobe 结果）。 */
+  width?: number
+  /** 视频画面高度。 */
+  height?: number
+}
+
+export type Vr360Detection = {
+  profile: Vr360Profile
+  /** 文件名/路径里出现了明确的 VR 或全景关键词，可以放心自动进入 VR 模式。 */
+  confident: boolean
+}
+
+// 关键词分两类：明确的关键词按子串匹配（"vr360" 里也含 "360"），
+// 容易误伤的两字母缩写按独立词元匹配（避免 "1ou" / "sivr" 之类误判）。
+const PANORAMA_SUBSTRINGS = ['360', 'equirect', 'insta360', 'pano', 'vuze', 'theta', '全景']
+const FISHEYE_SUBSTRINGS = ['fisheye', '鱼眼']
+const VR180_SUBSTRINGS = ['vr180', '180vr', '180°', '180度', '半景']
+const SBS_SUBSTRINGS = ['side-by-side', 'sidebyside', 'side_by_side', '左右']
+const OU_SUBSTRINGS = ['over-under', 'top-bottom', 'topbottom', '上下']
+const VR_TOKENS = ['vr']
+const SBS_TOKENS = ['sbs', 'hsbs', 'lr']
+const OU_TOKENS = ['ou', 'tb', 'vou', 'tou']
+
+function detectText(input: Vr360DetectInput): string {
+  return [input.path, input.relativePath, input.originalName, input.title]
+    .filter((value): value is string => Boolean(value))
+    .join(' ')
+    .toLowerCase()
+}
+
+// 文件名比标题可靠：标题里可能出现「VR」之类的普通单词，文件名里的 "vr" 通常
+// 是作品编号的一部分（如 sivr-270、ipvr00192）。
+function detectNameText(input: Vr360DetectInput): string {
+  return [input.path, input.relativePath, input.originalName]
+    .filter((value): value is string => Boolean(value))
+    .join(' ')
+    .toLowerCase()
+}
+
+function detectTokens(text: string): Set<string> {
+  return new Set(text.split(/[^a-z0-9]+/).filter(Boolean))
+}
+
+function hasSubstring(text: string, needles: string[]): boolean {
+  return needles.some((needle) => text.includes(needle))
+}
+
+function hasToken(tokens: Set<string>, needles: string[]): boolean {
+  return needles.some((needle) => tokens.has(needle))
+}
+
+function aspectRatio(input: Vr360DetectInput): number | null {
+  const width = input.width ?? 0
+  const height = input.height ?? 0
+  if (width <= 0 || height <= 0) return null
+  const ratio = width / height
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : null
+}
+
+/**
+ * 依据文件名/路径关键词与画幅比例推断 VR 配置。
+ *
+ * 关键词比画幅可靠：2:1 既可能是 360 单眼，也可能是 180 左右并排，所以比例只
+ * 在没有明确关键词时补默认值（4:1 ⇒ 左右并排；约 1:1 的 360 ⇒ 上下并排）。
+ */
+export function detectVr360Profile(input: Vr360DetectInput): Vr360Detection {
+  const text = detectText(input)
+  const nameText = detectNameText(input)
+  const tokens = detectTokens(text)
+
+  const fisheye = hasSubstring(text, FISHEYE_SUBSTRINGS)
+  const vr180 = hasSubstring(text, VR180_SUBSTRINGS)
+  const panorama = hasSubstring(text, PANORAMA_SUBSTRINGS)
+  const vrToken = hasToken(tokens, VR_TOKENS) || nameText.includes('vr')
+  const confident = fisheye || vr180 || panorama || vrToken
+
+  let projection: Vr360Projection = DEFAULT_VR360_PROFILE.projection
+  if (fisheye) projection = 'fisheye180'
+  else if (vr180) projection = 'equirect180'
+  // 只有 "VR" 一个信号、没有 360/全景关键词时，按更常见的 VR180 处理。
+  else if (vrToken && !panorama) projection = 'equirect180'
+
+  const sbs = hasSubstring(text, SBS_SUBSTRINGS) || hasToken(tokens, SBS_TOKENS)
+  const ou = hasSubstring(text, OU_SUBSTRINGS) || hasToken(tokens, OU_TOKENS)
+
+  let stereo: Vr360Stereo = 'mono'
+  if (sbs !== ou) stereo = sbs ? 'sbs' : 'ou'
+
+  const ratio = aspectRatio(input)
+  if (ratio !== null && stereo === 'mono') {
+    if (projection === 'equirect360') {
+      // 4:1 基本只可能是 360 左右并排（如 7680x1920）；
+      // 约 1:1 的 360 素材多为上下并排（如 3840x3840）。
+      if (ratio >= 3.4) stereo = 'sbs'
+      else if (ratio <= 1.05) stereo = 'ou'
+    } else {
+      // VR180 单眼是 1:1，左右并排是 2:1，上下并排是 1:2。
+      if (ratio >= 1.8 && ratio <= 2.2) stereo = 'sbs'
+      else if (ratio <= 0.6) stereo = 'ou'
+    }
+  }
+
+  return { profile: { projection, stereo }, confident }
+}
+
+const VR360_PREF_KEY = 'mebox.player.vr360'
+
+export type Vr360Preference = {
+  /** 是否按文件名/画幅自动进入 VR 模式；用户可以关掉，避免误判干扰正常播放。 */
+  autoDetect: boolean
+  /** 用户上次选定的投影与布局，作为下次手动进入 VR 模式时的默认值。 */
+  profile: Vr360Profile
+}
+
+export const DEFAULT_VR360_PREFERENCE: Vr360Preference = {
+  autoDetect: true,
+  profile: DEFAULT_VR360_PROFILE,
+}
+
+export function loadVr360Preference(): Vr360Preference {
+  if (typeof window === 'undefined') return DEFAULT_VR360_PREFERENCE
+  try {
+    const raw = window.localStorage.getItem(VR360_PREF_KEY)
+    if (!raw) return DEFAULT_VR360_PREFERENCE
+    const parsed = JSON.parse(raw) as Partial<Vr360Preference>
+    return {
+      autoDetect: parsed.autoDetect !== false,
+      profile: normalizeVr360Profile(parsed.profile),
+    }
+  } catch {
+    return DEFAULT_VR360_PREFERENCE
+  }
+}
+
+export function saveVr360Preference(preference: Vr360Preference): void {
+  try {
+    window.localStorage.setItem(
+      VR360_PREF_KEY,
+      JSON.stringify({
+        autoDetect: preference.autoDetect !== false,
+        profile: normalizeVr360Profile(preference.profile),
+      }),
+    )
+  } catch {
+    // 隐私模式下 localStorage 不可用；播放器仍可正常使用 VR 模式。
+  }
+}

web/src/utils/vr360Math.ts

@@ -0,0 +1,154 @@
+// VR360 播放用到的纯数学：3x3 旋转矩阵、设备姿态到相机姿态、透视投影。
+//
+// 坐标约定（与 W3C DeviceOrientation 规范一致，右手系）：
+//   x = 东（设备右侧），y = 北（设备顶部），z = 天空（设备屏幕朝外）
+//   相机看向相机局部坐标的 -z，设备平放时 -z 指向地面，因此设备平放时视角朝下，
+//   竖持手机（beta=90°）时视角水平向前 —— 与手机陀螺仪的实际手感一致。
+//
+// 所有 3x3 矩阵都是 WebGL 默认的列主序（column-major）Float32Array(9)，
+// 可以直接交给 gl.uniformMatrix3fv，不需要转置。
+
+export type Mat3 = Float32Array
+
+export function degToRad(degrees: number): number {
+  return (degrees * Math.PI) / 180
+}
+
+export function clampNumber(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min
+  return Math.min(max, Math.max(min, value))
+}
+
+export function createMat3(
+  m00: number, m10: number, m20: number,
+  m01: number, m11: number, m21: number,
+  m02: number, m12: number, m22: number,
+): Mat3 {
+  // WebGL 列主序内存布局：[col0, col1, col2]
+  return new Float32Array([m00, m10, m20, m01, m11, m21, m02, m12, m22])
+}
+
+export function identity3(): Mat3 {
+  return createMat3(1, 0, 0, 0, 1, 0, 0, 0, 1)
+}
+
+export function rotationX(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(1, 0, 0, 0, c, s, 0, -s, c)
+}
+
+export function rotationY(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(c, 0, -s, 0, 1, 0, s, 0, c)
+}
+
+export function rotationZ(radians: number): Mat3 {
+  const c = Math.cos(radians)
+  const s = Math.sin(radians)
+  return createMat3(c, s, 0, -s, c, 0, 0, 0, 1)
+}
+
+/** 先施加 b，再施加 a（即矩阵乘积 a·b）。 */
+export function multiply3(a: Mat3, b: Mat3): Mat3 {
+  const out = new Float32Array(9)
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) {
+      let sum = 0
+      for (let k = 0; k < 3; k++) {
+        sum += a[k * 3 + row] * b[col * 3 + k]
+      }
+      out[col * 3 + row] = sum
+    }
+  }
+  return out
+}
+
+/** 旋转矩阵的逆等于转置。 */
+export function transpose3(m: Mat3): Mat3 {
+  const out = new Float32Array(9)
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) {
+      out[col * 3 + row] = m[row * 3 + col]
+    }
+  }
+  return out
+}
+
+export function applyDirection(m: Mat3, x: number, y: number, z: number): [number, number, number] {
+  return [
+    m[0] * x + m[3] * y + m[6] * z,
+    m[1] * x + m[4] * y + m[7] * z,
+    m[2] * x + m[5] * y + m[8] * z,
+  ]
+}
+
+/** 相机在世界坐标中的朝向（相机局部 -z）。 */
+export function cameraForward(camera: Mat3): [number, number, number] {
+  const forward = applyDirection(camera, 0, 0, -1)
+  const length = Math.hypot(forward[0], forward[1], forward[2]) || 1
+  return [forward[0] / length, forward[1] / length, forward[2] / length]
+}
+
+/** 相机朝向的水平方位角（0 = +y 即正北，顺时针转向 +x 即正东）。 */
+export function forwardYaw(forward: [number, number, number]): number {
+  return Math.atan2(forward[0], forward[1])
+}
+
+/** 相机朝向的俯仰角（+ 抬头，- 低头）。 */
+export function forwardPitch(forward: [number, number, number]): number {
+  return Math.asin(clampNumber(forward[2], -1, 1))
+}
+
+/**
+ * 由「用户拖拽/默认视角」的方位角与俯仰角构造相机姿态。
+ * 默认（yaw = 0, pitch = 0）时相机水平看向 +y，画面中的地平线保持水平。
+ */
+export function cameraFromYawPitch(yaw: number, pitch: number): Mat3 {
+  return multiply3(rotationZ(-yaw), rotationX(Math.PI / 2 + pitch))
+}
+
+/**
+ * 由设备姿态构造相机姿态（W3C 规范：R = Rz(α)·Rx(β)·Ry(γ)），
+ * 再按屏幕旋转角做一次横滚校正，使画面正向与屏幕正向一致。
+ */
+export function cameraFromDeviceOrientation(
+  alpha: number,
+  beta: number,
+  gamma: number,
+  screenAngle: number,
+): Mat3 {
+  const device = multiply3(multiply3(rotationZ(alpha), rotationX(beta)), rotationY(gamma))
+  return multiply3(device, rotationZ(-screenAngle))
+}
+
+/**
+ * 在设备姿态之上叠加用户拖拽产生的视角偏移：水平方向围绕世界 z 轴旋转，
+ * 垂直方向围绕相机自身的右轴倾斜（小角度下等效于抬头/低头）。
+ */
+export function applyViewOffset(camera: Mat3, yawOffset: number, pitchOffset: number): Mat3 {
+  return multiply3(rotationZ(-yawOffset), multiply3(camera, rotationX(pitchOffset)))
+}
+
+/** 世界坐标 → 相机坐标的视图矩阵（纯旋转，所以就是转置）。 */
+export function viewMatrixFromCamera(camera: Mat3): Mat3 {
+  return transpose3(camera)
+}
+
+/** 标准透视投影矩阵（列主序 4x4）。 */
+export function perspectiveMatrix(
+  fovY: number,
+  aspect: number,
+  near: number,
+  far: number,
+): Float32Array {
+  const f = 1 / Math.tan(fovY / 2)
+  const rangeInv = 1 / (near - far)
+  return new Float32Array([
+    f / aspect, 0, 0, 0,
+    0, f, 0, 0,
+    0, 0, (far + near) * rangeInv, -1,
+    0, 0, 2 * far * near * rangeInv, 0,
+  ])
+}

web/src/utils/vr360Renderer.ts

@@ -0,0 +1,365 @@
+// 用一段 WebGL 把 <video> 贴到球面/半球面上，实现 360°/180° 全景播放。
+//
+// 不引入 three.js：整个渲染器只是一段着色器 + 一个网格 + 一张视频纹理，依赖
+// 极小，同时也不会把播放页首屏体积撑大（该模块由播放器按需懒加载）。
+//
+// 视频元素始终是同一个正在播放的 <video>，这里只把它当前的帧采样到球面上，
+// 因此 HLS、直连、115 云转码等所有播放方式都能直接复用。
+
+import type { Mat3 } from './vr360Math'
+import { perspectiveMatrix } from './vr360Math'
+import {
+  VR360_DEFAULT_FOV,
+  VR360_MAX_FOV,
+  VR360_MIN_FOV,
+  type Vr360Projection,
+} from './vr360'
+
+export type Vr360Renderer = {
+  setProjection(projection: Vr360Projection): void
+  /** 立体素材裁切：只取左眼所在的半张画面。 */
+  setFrameUv(scale: [number, number], offset: [number, number]): void
+  setView(view: Mat3): void
+  setFov(fovDeg: number): void
+  resize(width: number, height: number): void
+  draw(): void
+  dispose(): void
+}
+
+export type Vr360RendererOptions = {
+  /** WebGL 上下文丢失（移动端切后台、系统回收 GPU 资源）时回调，由调用方退出 VR 模式。 */
+  onContextLost?: () => void
+  /** 视频帧无法写入纹理（跨域污染等）时回调。 */
+  onTextureError?: (error: unknown) => void
+}
+
+const VERTEX_SHADER = `
+attribute vec3 aPosition;
+attribute vec2 aUv;
+uniform mat3 uView;
+uniform mat4 uProjection;
+uniform vec2 uUvScale;
+uniform vec2 uUvOffset;
+varying vec2 vUv;
+void main() {
+  vUv = aUv * uUvScale + uUvOffset;
+  gl_Position = uProjection * vec4(uView * aPosition, 1.0);
+}
+`
+
+const FRAGMENT_SHADER = `
+precision mediump float;
+uniform sampler2D uTexture;
+varying vec2 vUv;
+void main() {
+  gl_FragColor = texture2D(uTexture, vUv);
+}
+`
+
+// 球面半径为 1 个单位，相机固定在球心，远近裁剪面据此选取。
+const NEAR_PLANE = 0.1
+const FAR_PLANE = 10
+
+type Mesh = {
+  positions: Float32Array
+  uvs: Float32Array
+  indices: Uint16Array
+  indexCount: number
+}
+
+type GridPoint = {
+  position: [number, number, number]
+  uv: [number, number]
+}
+
+function buildGrid(
+  columns: number,
+  rows: number,
+  point: (col: number, row: number) => GridPoint,
+): Mesh {
+  const positions = new Float32Array((columns + 1) * (rows + 1) * 3)
+  const uvs = new Float32Array((columns + 1) * (rows + 1) * 2)
+  for (let row = 0; row <= rows; row++) {
+    for (let col = 0; col <= columns; col++) {
+      const index = row * (columns + 1) + col
+      const { position, uv } = point(col, row)
+      positions[index * 3] = position[0]
+      positions[index * 3 + 1] = position[1]
+      positions[index * 3 + 2] = position[2]
+      uvs[index * 2] = uv[0]
+      uvs[index * 2 + 1] = uv[1]
+    }
+  }
+
+  const indices = new Uint16Array(columns * rows * 6)
+  let cursor = 0
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < columns; col++) {
+      const topLeft = row * (columns + 1) + col
+      const topRight = topLeft + 1
+      const bottomLeft = topLeft + columns + 1
+      const bottomRight = bottomLeft + 1
+      indices[cursor++] = topLeft
+      indices[cursor++] = bottomLeft
+      indices[cursor++] = topRight
+      indices[cursor++] = topRight
+      indices[cursor++] = bottomLeft
+      indices[cursor++] = bottomRight
+    }
+  }
+
+  return { positions, uvs, indices, indexCount: indices.length }
+}
+
+/**
+ * 等距柱状投影：水平覆盖 ±span，垂直覆盖 -90°~+90°。
+ * u 从 0（左端）到 1（右端），v 从 0（画面顶部）到 1（画面底部）。
+ */
+function buildEquirectMesh(span: number): Mesh {
+  const columns = 96
+  const rows = 48
+  return buildGrid(columns, rows, (col, row) => {
+    const lambda = -span + (2 * span * col) / columns
+    const phi = -Math.PI / 2 + (Math.PI * row) / rows
+    const cosPhi = Math.cos(phi)
+    return {
+      position: [Math.sin(lambda) * cosPhi, Math.cos(lambda) * cosPhi, Math.sin(phi)],
+      uv: [(lambda + span) / (2 * span), 0.5 - phi / Math.PI],
+    }
+  })
+}
+
+/**
+ * 180° 鱼眼（等距投影）：画面中心是正前方，纹理半径 r 与偏角 θ 成正比。
+ * 方画幅内切圆之外的区域不参与采样，标准 VR180 鱼眼素材即如此。
+ */
+function buildFisheyeMesh(): Mesh {
+  const radial = 64
+  const azimuth = 96
+  const thetaMax = Math.PI / 2
+  return buildGrid(azimuth, radial, (col, row) => {
+    const psi = (2 * Math.PI * col) / azimuth
+    const theta = (thetaMax * row) / radial
+    const sinTheta = Math.sin(theta)
+    const radius = theta / thetaMax
+    return {
+      position: [sinTheta * Math.cos(psi), Math.cos(theta), sinTheta * Math.sin(psi)],
+      uv: [0.5 + 0.5 * radius * Math.cos(psi), 0.5 - 0.5 * radius * Math.sin(psi)],
+    }
+  })
+}
+
+function buildMesh(projection: Vr360Projection): Mesh {
+  if (projection === 'fisheye180') return buildFisheyeMesh()
+  if (projection === 'equirect180') return buildEquirectMesh(Math.PI / 2)
+  return buildEquirectMesh(Math.PI)
+}
+
+function compileShader(gl: WebGLRenderingContext, type: number, source: string): WebGLShader | null {
+  const shader = gl.createShader(type)
+  if (!shader) return null
+  gl.shaderSource(shader, source)
+  gl.compileShader(shader)
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    gl.deleteShader(shader)
+    return null
+  }
+  return shader
+}
+
+/**
+ * 在给定画布上创建全景渲染器；浏览器不支持 WebGL 时返回 null，调用方据此
+ * 退回普通播放，而不是给用户一个黑屏。
+ */
+export function createVr360Renderer(
+  canvas: HTMLCanvasElement,
+  video: HTMLVideoElement,
+  options: Vr360RendererOptions = {},
+): Vr360Renderer | null {
+  const attributes: WebGLContextAttributes = {
+    alpha: false,
+    antialias: false,
+    depth: false,
+    stencil: false,
+    premultipliedAlpha: false,
+    preserveDrawingBuffer: false,
+    powerPreference: 'high-performance',
+  }
+  const gl = (canvas.getContext('webgl2', attributes) ??
+    canvas.getContext('webgl', attributes)) as WebGLRenderingContext | null
+  if (!gl) return null
+
+  const vertexShader = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER)
+  const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER)
+  if (!vertexShader || !fragmentShader) return null
+  const program = gl.createProgram()
+  if (!program) return null
+  gl.attachShader(program, vertexShader)
+  gl.attachShader(program, fragmentShader)
+  gl.linkProgram(program)
+  gl.deleteShader(vertexShader)
+  gl.deleteShader(fragmentShader)
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    gl.deleteProgram(program)
+    return null
+  }
+
+  const positionLocation = gl.getAttribLocation(program, 'aPosition')
+  const uvLocation = gl.getAttribLocation(program, 'aUv')
+  const viewLocation = gl.getUniformLocation(program, 'uView')
+  const projectionLocation = gl.getUniformLocation(program, 'uProjection')
+  const uvScaleLocation = gl.getUniformLocation(program, 'uUvScale')
+  const uvOffsetLocation = gl.getUniformLocation(program, 'uUvOffset')
+  const textureLocation = gl.getUniformLocation(program, 'uTexture')
+
+  const positionBuffer = gl.createBuffer()
+  const uvBuffer = gl.createBuffer()
+  const indexBuffer = gl.createBuffer()
+  const texture = gl.createTexture()
+  if (!positionBuffer || !uvBuffer || !indexBuffer || !texture) return null
+
+  gl.bindTexture(gl.TEXTURE_2D, texture)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR)
+  // 先放一张 1x1 黑色占位图，视频帧尚未就绪时也不会出现未定义内容。
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    gl.RGBA,
+    1,
+    1,
+    0,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    new Uint8Array([0, 0, 0, 255]),
+  )
+
+  gl.disable(gl.CULL_FACE)
+  gl.disable(gl.DEPTH_TEST)
+  gl.disable(gl.BLEND)
+  gl.clearColor(0, 0, 0, 1)
+
+  let indexCount = 0
+  let uvScale: [number, number] = [1, 1]
+  let uvOffset: [number, number] = [0, 0]
+  let view: Mat3 = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1])
+  let fov = VR360_DEFAULT_FOV
+  let displayWidth = 1
+  let displayHeight = 1
+  let disposed = false
+  let contextLost = false
+
+  const uploadMesh = (mesh: Mesh) => {
+    indexCount = mesh.indexCount
+    gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer)
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.positions, gl.STATIC_DRAW)
+    gl.bindBuffer(gl.ARRAY_BUFFER, uvBuffer)
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.uvs, gl.STATIC_DRAW)
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer)
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, mesh.indices, gl.STATIC_DRAW)
+  }
+  uploadMesh(buildMesh('equirect360'))
+
+  const handleContextLost = (event: Event) => {
+    // 必须 preventDefault，否则上下文不会被标记为可恢复；这里直接让上层退出 VR。
+    event.preventDefault()
+    contextLost = true
+    options.onContextLost?.()
+  }
+  canvas.addEventListener('webglcontextlost', handleContextLost)
+
+  return {
+    setProjection(projection: Vr360Projection) {
+      if (disposed) return
+      uploadMesh(buildMesh(projection))
+    },
+    setFrameUv(scale: [number, number], offset: [number, number]) {
+      uvScale = scale
+      uvOffset = offset
+    },
+    setView(next: Mat3) {
+      view = next
+    },
+    setFov(next: number) {
+      fov = Math.min(VR360_MAX_FOV, Math.max(VR360_MIN_FOV, next))
+    },
+    resize(nextWidth: number, nextHeight: number) {
+      if (disposed) return
+      // 画布位置与尺寸完全交给 CSS（inset-0 + 100%），绘制缓冲区只跟随它。
+      // 否则「观测到画布变大 → 设置更大的缓冲区 → 布局再次变大」会指数放大。
+      canvas.style.width = '100%'
+      canvas.style.height = '100%'
+      // 移动端按 DPR 渲染 4K 视频纹理代价很高，上限锁 2 倍。
+      const dpr = Math.min(2, Math.max(1, window.devicePixelRatio || 1))
+      displayWidth = Math.max(1, nextWidth)
+      displayHeight = Math.max(1, nextHeight)
+      const pixelWidth = Math.max(1, Math.round(displayWidth * dpr))
+      const pixelHeight = Math.max(1, Math.round(displayHeight * dpr))
+      if (canvas.width !== pixelWidth) canvas.width = pixelWidth
+      if (canvas.height !== pixelHeight) canvas.height = pixelHeight
+    },
+    draw() {
+      if (disposed || contextLost) return
+      if (canvas.width < 1 || canvas.height < 1) return
+
+      gl.viewport(0, 0, canvas.width, canvas.height)
+      gl.clear(gl.COLOR_BUFFER_BIT)
+
+      if (video.readyState >= 2 && video.videoWidth > 0) {
+        try {
+          gl.bindTexture(gl.TEXTURE_2D, texture)
+          gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0)
+          gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, video)
+        } catch (error) {
+          options.onTextureError?.(error)
+        }
+      }
+
+      gl.useProgram(program)
+      gl.uniformMatrix3fv(viewLocation, false, view)
+      gl.uniformMatrix4fv(
+        projectionLocation,
+        false,
+        perspectiveMatrix(
+          (fov * Math.PI) / 180,
+          displayWidth / displayHeight,
+          NEAR_PLANE,
+          FAR_PLANE,
+        ),
+      )
+      gl.uniform2f(uvScaleLocation, uvScale[0], uvScale[1])
+      gl.uniform2f(uvOffsetLocation, uvOffset[0], uvOffset[1])
+      gl.uniform1i(textureLocation, 0)
+
+      gl.activeTexture(gl.TEXTURE0)
+      gl.bindTexture(gl.TEXTURE_2D, texture)
+
+      gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer)
+      gl.enableVertexAttribArray(positionLocation)
+      gl.vertexAttribPointer(positionLocation, 3, gl.FLOAT, false, 0, 0)
+
+      gl.bindBuffer(gl.ARRAY_BUFFER, uvBuffer)
+      gl.enableVertexAttribArray(uvLocation)
+      gl.vertexAttribPointer(uvLocation, 2, gl.FLOAT, false, 0, 0)
+
+      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer)
+      gl.drawElements(gl.TRIANGLES, indexCount, gl.UNSIGNED_SHORT, 0)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      canvas.removeEventListener('webglcontextlost', handleContextLost)
+      gl.bindBuffer(gl.ARRAY_BUFFER, null)
+      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, null)
+      gl.deleteBuffer(positionBuffer)
+      gl.deleteBuffer(uvBuffer)
+      gl.deleteBuffer(indexBuffer)
+      gl.deleteTexture(texture)
+      gl.deleteProgram(program)
+      // 主动释放上下文：移动端同时存活多个 WebGL 上下文会被浏览器强制回收。
+      gl.getExtension('WEBGL_lose_context')?.loseContext()
+    },
+  }
+}