feat: VR metadata support for VideoFile

graphql/schema/schema.graphql

@@ -427,7 +427,8 @@ type Mutation {
   destroyFiles(ids: [ID!]!): Boolean!
 
   fileSetFingerprints(input: FileSetFingerprintsInput!): Boolean!
-  "Reveal the file in the system file manager"
+  fileSetVRMetadata(input: FileSetVRMetadataInput!): Boolean!
+  "Reveal file system file manager"
   revealFileInFileManager(id: ID!): Boolean!
   "Reveal the folder in the system file manager"
   revealFolderInFileManager(id: ID!): Boolean!

graphql/schema/types/file.graphql

@@ -93,6 +93,10 @@ type VideoFile implements BaseFile {
   frame_rate: Float!
   bit_rate: Int!
 
+  projection: String
+  stereo_mode: String
+  vr_corrections: VRCorrections
+
   scenes: [Scene!]!
 
   created_at: Time!
@@ -170,9 +174,28 @@ input SetFingerprintsInput {
 }
 
 input FileSetFingerprintsInput {
-  id: ID!
-  "only supplied fingerprint types will be modified"
-  fingerprints: [SetFingerprintsInput!]!
+	id: ID!
+	"only supplied fingerprint types modified"
+	fingerprints: [SetFingerprintsInput!]!
+}
+
+type VRCorrections {
+	horizontal_offset: Float
+	vertical_offset: Float
+	alpha_mode: String
+}
+
+input FileSetVRMetadataInput {
+	id: ID!
+	projection: String
+	stereo_mode: String
+	vr_corrections: VRCorrectionsInput
+}
+
+input VRCorrectionsInput {
+	horizontal_offset: Float
+	vertical_offset: Float
+	alpha_mode: String
 }
 
 type FindFilesResultType {

internal/api/resolver_mutation_file.go

@@ -331,6 +331,41 @@ func (r *mutationResolver) FileSetFingerprints(ctx context.Context, input FileSe
 	return true, nil
 }
 
+func (r *mutationResolver) FileSetVRMetadata(ctx context.Context, input FileSetVRMetadataInput) (bool, error) {
+	fileIDInt, err := strconv.Atoi(input.ID)
+	if err != nil {
+		return false, fmt.Errorf("converting id: %w", err)
+	}
+	fileID := models.FileID(fileIDInt)
+
+	var projection *models.ProjectionEnum
+	if input.Projection != nil && *input.Projection != "" {
+		p := models.ProjectionEnum(*input.Projection)
+		projection = &p
+	}
+
+	var stereoMode *models.StereoModeEnum
+	if input.StereoMode != nil && *input.StereoMode != "" {
+		sm := models.StereoModeEnum(*input.StereoMode)
+		stereoMode = &sm
+	}
+
+	var vrCorrections *models.VRCorrections
+	if input.VrCorrections != nil {
+		vrCorrections = &models.VRCorrections{
+			HorizontalOffset: input.VrCorrections.HorizontalOffset,
+			VerticalOffset:   input.VrCorrections.VerticalOffset,
+			AlphaMode:        input.VrCorrections.AlphaMode,
+		}
+	}
+
+	if err := r.repository.File.ModifyVideoFileMetadata(ctx, fileID, projection, stereoMode, vrCorrections); err != nil {
+		return false, err
+	}
+
+	return true, nil
+}
+
 func (r *mutationResolver) RevealFileInFileManager(ctx context.Context, id string) (bool, error) {
 	// disallow if request did not come from localhost
 	if !session.IsLocalRequest(ctx) {

pkg/file/import.go

@@ -76,6 +76,9 @@ func (i *Importer) fileJSONToFile(ctx context.Context, fileJSON jsonschema.DirEn
 			BitRate:          ff.BitRate,
 			Interactive:      ff.Interactive,
 			InteractiveSpeed: ff.InteractiveSpeed,
+			Projection:       projectionPtr(ff.Projection),
+			StereoMode:       stereoModePtr(ff.StereoMode),
+			VRCorrections:    vrCorrectionsFromJSON(ff.VRCorrections),
 		}, nil
 	case *jsonschema.ImageFile:
 		baseFile, err := i.baseFileJSONToBaseFile(ctx, ff.BaseFile)
@@ -302,3 +305,30 @@ func (i *Importer) Update(ctx context.Context, id int) error {
 	// update not supported
 	return nil
 }
+
+func projectionPtr(s *string) *models.ProjectionEnum {
+	if s == nil {
+		return nil
+	}
+	p := models.ProjectionEnum(*s)
+	return &p
+}
+
+func stereoModePtr(s *string) *models.StereoModeEnum {
+	if s == nil {
+		return nil
+	}
+	m := models.StereoModeEnum(*s)
+	return &m
+}
+
+func vrCorrectionsFromJSON(jc *jsonschema.VRCorrections) *models.VRCorrections {
+	if jc == nil {
+		return nil
+	}
+	return &models.VRCorrections{
+		HorizontalOffset: jc.HorizontalOffset,
+		VerticalOffset:   jc.VerticalOffset,
+		AlphaMode:        jc.AlphaMode,
+	}
+}

pkg/models/file_vr.go

@@ -0,0 +1,125 @@
+package models
+
+import (
+	"fmt"
+	"io"
+	"strconv"
+)
+
+// ProjectionEnum describes how a video frame is mapped onto a sphere
+// or other projection surface. Generic naming; agnostic of any
+// particular player or device.
+type ProjectionEnum string
+
+const (
+	ProjectionEnumFlat            ProjectionEnum = "FLAT"
+	ProjectionEnumEquirectangular ProjectionEnum = "EQUIRECTANGULAR"
+	ProjectionEnumFisheye         ProjectionEnum = "FISHEYE"
+	ProjectionEnumMKX200          ProjectionEnum = "MKX200"
+	ProjectionEnumRF52            ProjectionEnum = "RF52"
+	ProjectionEnumDome            ProjectionEnum = "DOME"
+	ProjectionEnumCubemap         ProjectionEnum = "CUBEMAP"
+	ProjectionEnumRectilinear     ProjectionEnum = "RECTILINEAR"
+)
+
+var AllProjectionEnum = []ProjectionEnum{
+	ProjectionEnumFlat,
+	ProjectionEnumEquirectangular,
+	ProjectionEnumFisheye,
+	ProjectionEnumMKX200,
+	ProjectionEnumRF52,
+	ProjectionEnumDome,
+	ProjectionEnumCubemap,
+	ProjectionEnumRectilinear,
+}
+
+func (e ProjectionEnum) IsValid() bool {
+	switch e {
+	case ProjectionEnumFlat, ProjectionEnumEquirectangular, ProjectionEnumFisheye,
+		ProjectionEnumMKX200, ProjectionEnumRF52, ProjectionEnumDome,
+		ProjectionEnumCubemap, ProjectionEnumRectilinear:
+		return true
+	}
+	return false
+}
+
+func (e ProjectionEnum) String() string {
+	return string(e)
+}
+
+func (e *ProjectionEnum) UnmarshalGQL(v interface{}) error {
+	str, ok := v.(string)
+	if !ok {
+		return fmt.Errorf("enums must be strings")
+	}
+	*e = ProjectionEnum(str)
+	if !e.IsValid() {
+		return fmt.Errorf("%s is not a valid ProjectionEnum", str)
+	}
+	return nil
+}
+
+func (e ProjectionEnum) MarshalGQL(w io.Writer) {
+	fmt.Fprint(w, strconv.Quote(e.String()))
+}
+
+// StereoModeEnum describes how a stereoscopic video is laid out
+// across the frame. Generic naming.
+type StereoModeEnum string
+
+const (
+	StereoModeEnumMono              StereoModeEnum = "MONO"
+	StereoModeEnumSBS               StereoModeEnum = "SBS"
+	StereoModeEnumTB                StereoModeEnum = "TB"
+	StereoModeEnumCUV               StereoModeEnum = "CUV"
+	StereoModeEnumAlternatingFrames StereoModeEnum = "AF"
+	StereoModeEnumInterleavedRows   StereoModeEnum = "INTERLEAVED_ROWS"
+)
+
+var AllStereoModeEnum = []StereoModeEnum{
+	StereoModeEnumMono,
+	StereoModeEnumSBS,
+	StereoModeEnumTB,
+	StereoModeEnumCUV,
+	StereoModeEnumAlternatingFrames,
+	StereoModeEnumInterleavedRows,
+}
+
+func (e StereoModeEnum) IsValid() bool {
+	switch e {
+	case StereoModeEnumMono, StereoModeEnumSBS, StereoModeEnumTB, StereoModeEnumCUV,
+		StereoModeEnumAlternatingFrames, StereoModeEnumInterleavedRows:
+		return true
+	}
+	return false
+}
+
+func (e StereoModeEnum) String() string {
+	return string(e)
+}
+
+func (e *StereoModeEnum) UnmarshalGQL(v interface{}) error {
+	str, ok := v.(string)
+	if !ok {
+		return fmt.Errorf("enums must be strings")
+	}
+	*e = StereoModeEnum(str)
+	if !e.IsValid() {
+		return fmt.Errorf("%s is not a valid StereoModeEnum", str)
+	}
+	return nil
+}
+
+func (e StereoModeEnum) MarshalGQL(w io.Writer) {
+	fmt.Fprint(w, strconv.Quote(e.String()))
+}
+
+// VRCorrections holds optional per-video corrections commonly
+// applied when projecting stereoscopic or 360-degree content.
+// All fields are optional; nil means "unset".
+// AlphaMode follows DeoVR's alpha channel specification.
+type VRCorrections struct {
+	HorizontalOffset *float64 `json:"horizontal_offset"`
+	VerticalOffset   *float64 `json:"vertical_offset"`
+	AlphaMode        *string  `json:"alpha_mode"`
+}

pkg/models/jsonschema/file_folder.go

@@ -91,6 +91,17 @@ type VideoFile struct {
 
 	Interactive      bool `json:"interactive,omitempty"`
 	InteractiveSpeed *int `json:"interactive_speed,omitempty"`
+
+	Projection    *string        `json:"projection,omitempty"`
+	StereoMode    *string        `json:"stereo_mode,omitempty"`
+	VRCorrections *VRCorrections `json:"vr_corrections,omitempty"`
+}
+
+// VRCorrections mirrors models.VRCorrections for JSON import/export.
+type VRCorrections struct {
+	HorizontalOffset *float64 `json:"horizontal_offset,omitempty"`
+	VerticalOffset   *float64 `json:"vertical_offset,omitempty"`
+	AlphaMode        *string  `json:"alpha_mode,omitempty"`
 }
 
 type ImageFile struct {

pkg/models/model_file.go

@@ -289,6 +289,10 @@ type VideoFile struct {
 
 	Interactive      bool `json:"interactive"`
 	InteractiveSpeed *int `json:"interactive_speed"`
+
+	Projection    *ProjectionEnum `json:"projection"`
+	StereoMode    *StereoModeEnum `json:"stereo_mode"`
+	VRCorrections *VRCorrections  `json:"vr_corrections"`
 }
 
 func (f VideoFile) GetWidth() int {

pkg/models/repository_file.go

@@ -77,12 +77,28 @@ type FileFingerprintWriter interface {
 	DestroyFingerprints(ctx context.Context, fileID FileID, types []string) error
 }
 
+// FileVRMetadataWriter provides methods to update VR-related
+// metadata fields (projection, stereo_mode, vr_corrections)
+// on a video file. Each pointer argument is optional: a nil
+// value means "do not change this field". A non-nil zero value
+// means "set this field to zero / null".
+type FileVRMetadataWriter interface {
+	ModifyVideoFileMetadata(
+		ctx context.Context,
+		fileID FileID,
+		projection *ProjectionEnum,
+		stereoMode *StereoModeEnum,
+		vrCorrections *VRCorrections,
+	) error
+}
+
 // FileWriter provides all methods to modify files.
 type FileWriter interface {
 	FileCreator
 	FileUpdater
 	FileDestroyer
 	FileFingerprintWriter
+	FileVRMetadataWriter
 
 	UpdateCaptions(ctx context.Context, fileID FileID, captions []*VideoCaption) error
 }

pkg/sqlite/database.go

@@ -34,7 +34,7 @@ const (
 	cacheSizeEnv = "STASH_SQLITE_CACHE_SIZE"
 )
 
-var appSchemaVersion uint = 85
+var appSchemaVersion uint = 86
 
 //go:embed migrations/*.sql
 var migrationsBox embed.FS