shared

package
v0.0.0-...-689375e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultImageThreshold = 0.90
	DefaultVideoThreshold = 0.85
	DefaultHashSize       = 16
	DefaultNumFrames      = 10
	DefaultNumWorkers     = 4
	DefaultBatchSize      = 1000
)
View Source
const (
	DefaultThumbnailSize    = 200
	DefaultThumbnailQuality = 80
	MaxL1ThumbnailCacheSize = 1000
)
View Source
const Version = "0.1.0"

Variables

View Source
var (
	ErrEmptyPath        = errors.New("path cannot be empty")
	ErrNullByte         = errors.New("path contains null byte")
	ErrProtectedSystem  = errors.New("access to system directory is forbidden")
	ErrNotADirectory    = errors.New("path is not a directory")
	ErrNotARegularFile  = errors.New("path is not a regular file")
	ErrUnsupportedMedia = errors.New("file format is not a supported media type")
)
View Source
var Aliases = map[string]string{
	".jpeg": ".jpg",
	".tiff": ".tif",
	".mpg":  ".mpeg",
}

Aliases maps alternative extensions to their canonical form.

View Source
var ExcludedFolders = map[string]struct{}{

	"$recycle.bin":              {},
	"$recycle":                  {},
	"recycler":                  {},
	"recycled":                  {},
	"system volume information": {},
	"windows":                   {},
	"appdata":                   {},

	".trash":          {},
	".trashes":        {},
	".spotlight-v100": {},
	".fseventsd":      {},
	".ds_store":       {},

	"lost+found": {},
	"trash":      {},

	".thumbnails": {},
	".thumb":      {},
	"thumbs":      {},

	"@eadir": {},

	".git": {},
	".svn": {},
	".hg":  {},

	"__pycache__":  {},
	".cache":       {},
	"node_modules": {},
	".venv":        {},
	"venv":         {},
}

ExcludedFolders contains folder names to skip during scanning.

View Source
var ImageExtensions = map[string]struct{}{
	".jpg":  {},
	".jpeg": {},
	".png":  {},
	".tif":  {},
	".tiff": {},
	".bmp":  {},
	".webp": {},
	".gif":  {},
	".ico":  {},
	".heic": {},
	".heif": {},
	".avif": {},
	".svg":  {},
	".raw":  {},
	".cr2":  {},
	".nef":  {},
	".arw":  {},
	".dng":  {},
	".orf":  {},
	".rw2":  {},
	".pef":  {},
	".srw":  {},
}

ImageExtensions contains all supported image file extensions (lowercase, with dot prefix).

View Source
var VideoExtensions = map[string]struct{}{
	".mp4":  {},
	".mov":  {},
	".avi":  {},
	".mkv":  {},
	".webm": {},
	".flv":  {},
	".wmv":  {},
	".m4v":  {},
	".mpeg": {},
	".mpg":  {},
	".3gp":  {},
	".ts":   {},
	".ogv":  {},
	".mts":  {},
	".m2ts": {},
	".vob":  {},
	".divx": {},
	".xvid": {},
	".asf":  {},
	".rm":   {},
	".rmvb": {},
}

VideoExtensions contains all supported video file extensions.

Functions

func ExifToolCandidates

func ExifToolCandidates() []string

ExifToolCandidates returns available exiftool binary names in PATH.

func FFmpegCandidates

func FFmpegCandidates() []string

FFmpegCandidates returns available ffmpeg binary names in PATH.

func FormatDuration

func FormatDuration(seconds float64) string

FormatDuration formats duration in human-readable format.

func FormatFileSize

func FormatFileSize(sizeBytes int64) string

FormatFileSize formats file size in human-readable format.

func GenerateImageThumbnail

func GenerateImageThumbnail(ctx context.Context, path string, size int) ([]byte, error)

GenerateImageThumbnail creates a JPEG thumbnail for an image file.

func GenerateVideoThumbnail

func GenerateVideoThumbnail(ctx context.Context, path string, size int) ([]byte, error)

GenerateVideoThumbnail creates a JPEG thumbnail for a video file using ffmpeg.

func IsExcludedPath

func IsExcludedPath(path string, excludedFolders map[string]struct{}) bool

IsExcludedPath checks if any component of the path is in the exclusion set.

func IsImage

func IsImage(path string) bool

IsImage returns true if the file extension is a known image type.

func IsImageFile

func IsImageFile(path string) bool

IsImageFile is an alias for IsImage.

func IsProtectedSystemPath

func IsProtectedSystemPath(cleanAbsPath string) bool

IsProtectedSystemPath checks whether an absolute path falls into a forbidden OS system directory.

func IsVideo

func IsVideo(path string) bool

IsVideo returns true if the file extension is a known video type.

func IsVideoFile

func IsVideoFile(path string) bool

IsVideoFile is an alias for IsVideo.

func NormaliseExt

func NormaliseExt(ext string) string

NormaliseExt lowercases and resolves aliases (.jpeg → .jpg).

func OpenImageFile

func OpenImageFile(ctx context.Context, path string) (image.Image, error)

OpenImageFile opens an image from any format supported by imaging or ffmpeg.

func OpenNativeFolderDialog

func OpenNativeFolderDialog(ctx context.Context) (string, bool, error)

OpenNativeFolderDialog opens a native folder selection dialog. Returns the selected folder path, whether a dialog tool is available, and any error.

func PathForBin

func PathForBin(bin, p string) string

PathForBin returns the path in the format expected by the given binary. When bin is a Windows executable (.exe), WSL /mnt/ paths are converted.

func SetThumbnailDBPool

func SetThumbnailDBPool(pool *pgxpool.Pool)

SetThumbnailDBPool sets the PostgreSQL pool for L2 persistent thumbnail caching.

func SevenZipCandidates

func SevenZipCandidates() []string

SevenZipCandidates returns available 7z binary names in PATH.

func ToWindowsPath

func ToWindowsPath(p string) string

ToWindowsPath converts a WSL /mnt/X/... path to a Windows X:\... path. Windows-native executables (e.g. ffmpeg.exe) cannot access /mnt/ paths directly.

func TranslateHostPath

func TranslateHostPath(p string) string

TranslateHostPath converts paths copied from a Windows file explorer (e.g. D:\Photos or \\wsl$\Ubuntu\home\me) into their equivalent on a Linux/macOS runner (/mnt/d/Photos, /home/me).

func ValidateMediaFilePath

func ValidateMediaFilePath(raw string) (string, error)

ValidateMediaFilePath verifies that raw resolves to a safe, existing regular file with an allowed media extension.

func ValidateSafeDirPath

func ValidateSafeDirPath(raw string) (string, error)

ValidateSafeDirPath verifies that raw resolves to a safe, existing directory.

func ValidateSafePath

func ValidateSafePath(raw string) (string, error)

ValidateSafePath cleans and canonicalizes a path, rejecting null bytes, relative traversal, and protected system directories.

Types

type FileInfo

type FileInfo struct {
	Path string
	Name string
	Size int64
	Ext  string
}

FileInfo holds metadata about a discovered file.

func FindAllMediaFiles

func FindAllMediaFiles(folder string) ([]FileInfo, error)

FindAllMediaFiles returns all image and video files.

func FindFilesByExtension

func FindFilesByExtension(folder string, extensions map[string]struct{}, excludedFolders map[string]struct{}) ([]FileInfo, error)

FindFilesByExtension walks the folder tree once and returns all files matching the given extensions. This replaces the Python version which called rglob() twice per extension (82+ traversals).

func FindImageFiles

func FindImageFiles(folder string) ([]FileInfo, error)

FindImageFiles returns all image files in the given folder.

func FindVideoFiles

func FindVideoFiles(folder string) ([]FileInfo, error)

FindVideoFiles returns all video files in the given folder.

type Job

type Job struct {
	ID        string    `json:"id"`
	Status    JobStatus `json:"status"`
	Progress  float64   `json:"progress"`
	Message   string    `json:"message,omitempty"`
	Error     string    `json:"error,omitempty"`
	StartedAt time.Time `json:"started_at"`
	DoneAt    time.Time `json:"done_at,omitempty"`
}

Job is a base type embedded in module-specific jobs. Notice: context.Context is intentionally NOT stored here to adhere to Go guidelines. Context is threaded through call chains and cancellation is managed via JobStore.

func NewJob

func NewJob() Job

NewJob creates a new job with a unique ID and initial status.

type JobStatus

type JobStatus string

JobStatus represents the state of a background job.

const (
	JobStatusPending   JobStatus = "pending"
	JobStatusRunning   JobStatus = "running"
	JobStatusDone      JobStatus = "done"
	JobStatusFailed    JobStatus = "failed"
	JobStatusPlanned   JobStatus = "planned"
	JobStatusCancelled JobStatus = "cancelled"
)

type JobStore

type JobStore[T any] struct {
	// contains filtered or unexported fields
}

JobStore is a thread-safe generic store for background jobs and their cancellation functions.

func NewJobStore

func NewJobStore[T any]() *JobStore[T]

NewJobStore creates a new JobStore.

func (*JobStore[T]) Cancel

func (s *JobStore[T]) Cancel(id string) bool

Cancel invokes the cancel function associated with a job ID, if registered.

func (*JobStore[T]) Delete

func (s *JobStore[T]) Delete(id string)

Delete removes a job and its cancellation function by ID.

func (*JobStore[T]) Get

func (s *JobStore[T]) Get(id string) (*T, bool)

Get retrieves a job by ID.

func (*JobStore[T]) RegisterCancel

func (s *JobStore[T]) RegisterCancel(id string, cancel context.CancelFunc)

RegisterCancel associates a cancellation function with a job.

func (*JobStore[T]) Set

func (s *JobStore[T]) Set(id string, job *T)

Set stores a job.

func (*JobStore[T]) StartCleanup

func (s *JobStore[T]) StartCleanup(ctx context.Context, ttl time.Duration, getDoneAt func(*T) time.Time)

StartCleanup runs a background goroutine that removes jobs older than ttl. It terminates when the provided context is cancelled.

type ThumbnailCache

type ThumbnailCache struct {
	// contains filtered or unexported fields
}

ThumbnailCache provides a thread-safe cache for generated thumbnails.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址