media

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package media resolves authorized media requests to fixed Immich-generated variants.

Index

Constants

View Source
const (
	ChapterStatusQueued     = "queued"
	ChapterStatusProcessing = "processing"
	ChapterStatusComplete   = "complete"
	ChapterStatusFailed     = "failed"
)

Chapter result statuses. Queued and processing both read as pending to browsers; complete carries the chapters, which may be none.

Variables

This section is empty.

Functions

func AvatarURL

func AvatarURL(personID, faceID, version string) string

AvatarURL is the private browser URL for a Person's avatar. The version carries both the chosen face and that face's Immich version.

func ContentVersion

func ContentVersion(asset immich.Asset) string

ContentVersion names what a photo or video shows, so its browser URL and cache entry change only when that does. Immich touches updatedAt and re-encodes the thumbhash whenever it rebuilds thumbnails, so neither is part of it.

func FaceThumbnailURL

func FaceThumbnailURL(sourceID, version string) string

FaceThumbnailURL is the private browser URL for an Immich person thumbnail, versioned by the person's last change so a new featured photo gets a new URL.

func PublicChapterStatus

func PublicChapterStatus(status string) string

PublicChapterStatus folds the stored status into the three states the browser shows: pending, complete, or failed. No row means pending.

func RegisterRoutes

func RegisterRoutes(e *echo.Echo, m *Module, requirePerson, requireCurator echo.MiddlewareFunc)

RegisterRoutes requires the Curator guard for source and imported media. Avatars need only a signed-in Person: everyone reads their own, Curators read everyone's.

func RegisterSignedRoutes added in v0.3.0

func RegisterSignedRoutes(e *echo.Echo, m *Module, authorize AuthorizeEntry, publicURL string, requirePerson echo.MiddlewareFunc)

RegisterSignedRoutes lets a signed-in Person mint a media URL that a TV can fetch without the session cookie, and serves those URLs. publicURL roots them, because the TV needs a full address. The serving routes sit behind no guard: the token names the Person, and authorize runs for that Person on every request, so removing access stops an unexpired URL.

func RegisterViewerRoutes

func RegisterViewerRoutes(e *echo.Echo, m *Module, authorize AuthorizeEntry, requirePerson, requireCurator echo.MiddlewareFunc)

RegisterViewerRoutes scopes browser caches to the authenticated Person or an explicit Curator preview. The selected Person is part of every URL, so one browser can cache several previews without mixing them.

Types

type AuthorizeEntry

type AuthorizeEntry func(context.Context, string, string, string) error

AuthorizeEntry applies Publishing's evaluator before any media response.

type EnqueueChapters

type EnqueueChapters func(ctx context.Context, tx bun.Tx, mediaItemID, checksum string) error

EnqueueChapters commits durable extraction with the caller's transaction. It never runs ffprobe inline.

type EntryMedia

type EntryMedia struct {
	SourceID   string
	Filename   string
	Kind       string
	CapturedAt time.Time
	Checksum   string
	Edited     *bool
	Width      *int
	Height     *int
}

EntryMedia is the imported source identity behind one Album Entry, with the facts that tell whether Immich still shows the same content.

type Module

type Module struct {

	// EnqueueChapters commits extraction tasks with their rows. Leave it nil
	// only where no chapter work is ever requested, such as media-only tests.
	EnqueueChapters EnqueueChapters
	// Now dates signed media URLs. Leave it nil outside tests.
	Now func() time.Time
	// contains filtered or unexported fields
}

func New

func New(db *bun.DB, source Source) *Module

func (*Module) BackfillChapters

func (m *Module) BackfillChapters(ctx context.Context) (int, error)

BackfillChapters queues extraction for every video that has never been probed, so enabling the capability covers import-era videos, and re-enqueues rows still queued or processing from a run that ended abruptly. The queue deduplicates a task that is still alive, so it is safe to run at every start. It reports how many videos were queued.

func (*Module) EntryOriginal

func (m *Module) EntryOriginal(ctx context.Context, id, version string) (EntryMedia, error)

EntryOriginal resolves the source asset and filename behind a photo or video download.

func (*Module) EntryPlayback

func (m *Module) EntryPlayback(ctx context.Context, id, version string) (EntryMedia, error)

EntryPlayback resolves the source asset behind a video stream. Photos have no playback, so they are not found here.

func (*Module) EntryThumbnail

func (m *Module) EntryThumbnail(ctx context.Context, id, version string) (EntryMedia, error)

EntryThumbnail resolves a content-versioned entry only after verifying active membership in a completed Album. A stale URL must never serve different bytes.

func (*Module) ExtractChapters

func (m *Module) ExtractChapters(ctx context.Context, mediaItemID, checksum string, finalAttempt bool) (returnErr error)

ExtractChapters is the worker body. It probes outside any transaction and writes only while the row still names the checksum it was asked about, so a task that finishes late cannot replace a newer result. finalAttempt decides whether a failure is shown as retrying or as failed.

func (*Module) FaceThumbnail

func (m *Module) FaceThumbnail(ctx context.Context, sourceID, version string) (string, error)

FaceThumbnail authorizes a cached Immich face at the requested version and returns the Immich person ID to fetch. A superseded version is not found, so once a refresh records a newer version the old URL stops serving.

func (*Module) PersonAvatar

func (m *Module) PersonAvatar(ctx context.Context, personID, version string) (string, error)

PersonAvatar authorizes a Person's avatar at the requested version and returns the linked Immich person ID to fetch.

func (*Module) RequestChapters

func (m *Module) RequestChapters(ctx context.Context, tx bun.Tx, mediaItemID models.UUID, checksum string) error

RequestChapters records that a video needs extraction at its current checksum and enqueues the work in the same transaction. An existing result at the same checksum is kept, so repeated imports never redo finished work.

func (*Module) RetryChapters

func (m *Module) RetryChapters(ctx context.Context, mediaItemID string) error

RetryChapters requeues a failed or stalled extraction at the current checksum. A complete result needs no work and is left alone.

func (*Module) SignedPath added in v0.3.0

func (m *Module) SignedPath(ctx context.Context, personID, entryID, variant string) (string, error)

SignedPath mints the signed route for one Album Entry a Person may already view. The entry's current content version rides along unsigned: it only selects bytes, exactly as it does on the cookie routes.

func (*Module) SourceAssetThumbnail

func (m *Module) SourceAssetThumbnail(ctx context.Context, sourceID string) (immich.Thumbnail, error)

SourceAssetThumbnail reads an asset's generated thumbnail straight from Immich for a Curator reviewing source changes.

func (*Module) SourceCover

func (m *Module) SourceCover(ctx context.Context, albumID string) (immich.Thumbnail, error)

type SignRequest added in v0.3.0

type SignRequest struct {
	EntryID string `json:"entry_id" validate:"required,max=64"`
	Variant string `json:"variant" validate:"required,oneof=playback preview"`
}

SignRequest asks for a URL that a TV can fetch without the session cookie. A video is signed as its playback stream and a photo as its large preview.

type SignedURL added in v0.3.0

type SignedURL struct {
	URL string `json:"url"`
}

SignedURL is an absolute address that authorizes on its own for a few hours.

type Source

Source exposes source album lookup, generated image variants, originals, ranged playback, and chapter probing.

Jump to

Keyboard shortcuts

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