Documentation
¶
Index ¶
- Constants
- Variables
- func ExifToolCandidates() []string
- func FFmpegCandidates() []string
- func FormatDuration(seconds float64) string
- func FormatFileSize(sizeBytes int64) string
- func GenerateImageThumbnail(ctx context.Context, path string, size int) ([]byte, error)
- func GenerateVideoThumbnail(ctx context.Context, path string, size int) ([]byte, error)
- func IsExcludedPath(path string, excludedFolders map[string]struct{}) bool
- func IsImage(path string) bool
- func IsImageFile(path string) bool
- func IsProtectedSystemPath(cleanAbsPath string) bool
- func IsVideo(path string) bool
- func IsVideoFile(path string) bool
- func NormaliseExt(ext string) string
- func OpenImageFile(ctx context.Context, path string) (image.Image, error)
- func OpenNativeFolderDialog(ctx context.Context) (string, bool, error)
- func PathForBin(bin, p string) string
- func SetThumbnailDBPool(pool *pgxpool.Pool)
- func SevenZipCandidates() []string
- func ToWindowsPath(p string) string
- func TranslateHostPath(p string) string
- func ValidateMediaFilePath(raw string) (string, error)
- func ValidateSafeDirPath(raw string) (string, error)
- func ValidateSafePath(raw string) (string, error)
- type FileInfo
- type Job
- type JobStatus
- type JobStore
- func (s *JobStore[T]) Cancel(id string) bool
- func (s *JobStore[T]) Delete(id string)
- func (s *JobStore[T]) Get(id string) (*T, bool)
- func (s *JobStore[T]) RegisterCancel(id string, cancel context.CancelFunc)
- func (s *JobStore[T]) Set(id string, job *T)
- func (s *JobStore[T]) StartCleanup(ctx context.Context, ttl time.Duration, getDoneAt func(*T) time.Time)
- type ThumbnailCache
Constants ¶
const ( DefaultImageThreshold = 0.90 DefaultVideoThreshold = 0.85 DefaultHashSize = 16 DefaultNumFrames = 10 DefaultNumWorkers = 4 DefaultBatchSize = 1000 )
const ( DefaultThumbnailSize = 200 DefaultThumbnailQuality = 80 MaxL1ThumbnailCacheSize = 1000 )
const Version = "0.1.0"
Variables ¶
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") )
var Aliases = map[string]string{
".jpeg": ".jpg",
".tiff": ".tif",
".mpg": ".mpeg",
}
Aliases maps alternative extensions to their canonical form.
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.
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).
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 ¶
FormatDuration formats duration in human-readable format.
func FormatFileSize ¶
FormatFileSize formats file size in human-readable format.
func GenerateImageThumbnail ¶
GenerateImageThumbnail creates a JPEG thumbnail for an image file.
func GenerateVideoThumbnail ¶
GenerateVideoThumbnail creates a JPEG thumbnail for a video file using ffmpeg.
func IsExcludedPath ¶
IsExcludedPath checks if any component of the path is in the exclusion set.
func IsProtectedSystemPath ¶
IsProtectedSystemPath checks whether an absolute path falls into a forbidden OS system directory.
func NormaliseExt ¶
NormaliseExt lowercases and resolves aliases (.jpeg → .jpg).
func OpenImageFile ¶
OpenImageFile opens an image from any format supported by imaging or ffmpeg.
func OpenNativeFolderDialog ¶
OpenNativeFolderDialog opens a native folder selection dialog. Returns the selected folder path, whether a dialog tool is available, and any error.
func PathForBin ¶
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 ¶
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 ¶
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 ¶
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 ¶
ValidateMediaFilePath verifies that raw resolves to a safe, existing regular file with an allowed media extension.
func ValidateSafeDirPath ¶
ValidateSafeDirPath verifies that raw resolves to a safe, existing directory.
func ValidateSafePath ¶
ValidateSafePath cleans and canonicalizes a path, rejecting null bytes, relative traversal, and protected system directories.
Types ¶
type FileInfo ¶
FileInfo holds metadata about a discovered file.
func FindAllMediaFiles ¶
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 ¶
FindImageFiles returns all image files in the given folder.
func FindVideoFiles ¶
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.
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 (*JobStore[T]) Cancel ¶
Cancel invokes the cancel function associated with a job ID, if registered.
func (*JobStore[T]) RegisterCancel ¶
func (s *JobStore[T]) RegisterCancel(id string, cancel context.CancelFunc)
RegisterCancel associates a cancellation function with a job.
type ThumbnailCache ¶
type ThumbnailCache struct {
// contains filtered or unexported fields
}
ThumbnailCache provides a thread-safe cache for generated thumbnails.