Documentation
¶
Overview ¶
Package media resolves authorized media requests to fixed Immich-generated variants.
Index ¶
- Constants
- func AvatarURL(personID, faceID, version string) string
- func ContentVersion(asset immich.Asset) string
- func FaceThumbnailURL(sourceID, version string) string
- func PublicChapterStatus(status string) string
- func RegisterRoutes(e *echo.Echo, m *Module, requirePerson, requireCurator echo.MiddlewareFunc)
- func RegisterSignedRoutes(e *echo.Echo, m *Module, authorize AuthorizeEntry, publicURL string, ...)
- func RegisterViewerRoutes(e *echo.Echo, m *Module, authorize AuthorizeEntry, ...)
- type AuthorizeEntry
- type EnqueueChapters
- type EntryMedia
- type Module
- func (m *Module) BackfillChapters(ctx context.Context) (int, error)
- func (m *Module) EntryOriginal(ctx context.Context, id, version string) (EntryMedia, error)
- func (m *Module) EntryPlayback(ctx context.Context, id, version string) (EntryMedia, error)
- func (m *Module) EntryThumbnail(ctx context.Context, id, version string) (EntryMedia, error)
- func (m *Module) ExtractChapters(ctx context.Context, mediaItemID, checksum string, finalAttempt bool) (returnErr error)
- func (m *Module) FaceThumbnail(ctx context.Context, sourceID, version string) (string, error)
- func (m *Module) PersonAvatar(ctx context.Context, personID, version string) (string, error)
- func (m *Module) RequestChapters(ctx context.Context, tx bun.Tx, mediaItemID models.UUID, checksum string) error
- func (m *Module) RetryChapters(ctx context.Context, mediaItemID string) error
- func (m *Module) SignedPath(ctx context.Context, personID, entryID, variant string) (string, error)
- func (m *Module) SourceAssetThumbnail(ctx context.Context, sourceID string) (immich.Thumbnail, error)
- func (m *Module) SourceCover(ctx context.Context, albumID string) (immich.Thumbnail, error)
- type SignRequest
- type SignedURL
- type Source
Constants ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
AuthorizeEntry applies Publishing's evaluator before any media response.
type EnqueueChapters ¶
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 (*Module) BackfillChapters ¶
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 ¶
EntryOriginal resolves the source asset and filename behind a photo or video download.
func (*Module) EntryPlayback ¶
EntryPlayback resolves the source asset behind a video stream. Photos have no playback, so they are not found here.
func (*Module) EntryThumbnail ¶
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 ¶
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 ¶
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 ¶
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
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.
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 ¶
type Source interface {
GetAlbum(context.Context, string) (immich.Album, error)
GetAsset(context.Context, string) (immich.Asset, error)
Thumbnail(context.Context, string) (immich.Thumbnail, error)
Preview(context.Context, string) (immich.Thumbnail, error)
Original(context.Context, string) (immich.Original, error)
Playback(context.Context, string, immich.PlaybackRequest) (immich.Playback, error)
Chapters(context.Context, string) ([]ffprobe.Chapter, error)
PersonThumbnail(context.Context, string) (immich.Thumbnail, error)
}
Source exposes source album lookup, generated image variants, originals, ranged playback, and chapter probing.