IVideoCatalogService Interface¶

Interface to the video catalog database. This is the main interface for accessing and modifying video metadata, thumbnails, actors, tags, playlists, and more.

Access via scripting.GetVideoCatalogService().

Video Operations¶

Adding & Removing Videos¶

Method	Returns	Description
`AddVideo(path, title, video_length, description, genre, rating, link, preview, file_size, encrypted, IV)`	`long`	Add a new video to the catalog. Returns video ID.
`RemoveVideoByID(long video_file_id)`	`void`	Remove a video from the catalog by ID
`DeleteVideoFile(string file_path)`	`void`	Remove all videos with the given path
`MergeVideo(long video_id_to_remove, long keep_video_file_id)`	`void`	Merge source video into destination, keeping all thumbnails and keywords

Searching Videos¶

Method	Returns	Description
`SearchVideos(VideoQuery video_query)`	`VideoFileEntry[]`	Search for videos using a query filter
`SearchVideosFromString(string search_string)`	`VideoFileEntry[]`	Search for videos using a text string
`GetVideoFileID(string path)`	`long`	Get video ID for a path. Returns -1 if not found.
`GetVideoFileEntry(long video_file_id)`	`VideoFileEntry`	Get video entry by ID
`GetRandomVideoFileEntries(int max_nof_items)`	`Dictionary<long, VideoFileEntry>`	Get random videos
`GetNofVideos()`	`long`	Get total number of videos in catalog

Video Properties¶

Method	Returns	Description
`SetVideoProperty(long video_file_id, string property_name, string value)`	`void`	Set video property (FilePath, Title, Link, Description, Rating)
`SetVideoGenre(long video_file_id, string genre_title)`	`void`	Set video genre
`UpdateVideoFilePath(string Source, string Destination)`	`bool`	Change a video file path
`GetVideoFileImage(long video_file_id)`	`byte[]`	Get video preview image (JPEG)
`SetVideoFileImage(long video_file_id, byte[] image_data)`	`void`	Set video preview image

Extended Properties¶

Method	Returns	Description
`GetVideoFileExtendedProperty(long video_file_id)`	`ExtendedProperty[]`	Get all extended properties for a video
`SetVideoFileExtendedProperty(long video_file_id, string property, string value)`	`void`	Set an extended property value
`GetAllExtendedPropertyValues(string property_name)`	`ExtendedPropertyVideoValue[]`	Get all values for a property
`GetPropertyMeta(string property)`	`PropertyMeta[]`	Get meta properties
`SetPropertyMeta(string property, string aspect, string value)`	`void`	Set a meta property
`RemovePropertyMeta(string property, string aspect)`	`void`	Remove a meta property

Thumbnail Operations¶

Method	Returns	Description
`AddVideoThumbnail(ThumbnailEntry thumb_entry)`	`void`	Add a thumbnail to a video
`AddGetVideoThumbnail(ThumbnailEntry thumb_entry)`	`long`	Add thumbnail and return its ID
`GetThumbnail(long thumbnail_id)`	`ThumbnailEntry`	Get thumbnail data including image
`GetThumbnailImageFromID(long thumbnail_id)`	`byte[]`	Get thumbnail image (JPEG)
`GetThumbnailsForVideo(long video_file_id, bool include_image_data)`	`Dictionary<long, ThumbnailEntry>`	Get all thumbnails for a video
`GetThumbnailsIDsForVideo(long video_file_id)`	`long[]`	Get all thumbnail IDs for a video
`DeleteThumbnail(long thumbnail_id)`	`void`	Delete a thumbnail
`SearchThumbnails(VideoQuery video_query, SceneQuery scene_search)`	`SceneQueryResult`	Search thumbnails by keywords
`GetThumbnailExtendedProperty(long thumbnail_id)`	`ExtendedProperty[]`	Get extended properties for a thumbnail
`SetThumbnailExtendedProperty(long thumbnail_id, string property, string value)`	`void`	Set extended property on thumbnail

Tag Operations¶

Video Tags¶

Method	Returns	Description
`GetAllVideoTags()`	`Tag[]`	Get all video tags
`TagVideo(long video_file_id, string entered_keyword_string)`	`int`	Add tag(s) to a video
`CreateVideoTag(Tag tag)`	`Tag`	Create a new video tag
`DeleteVideoTagFromCatalog(int tag_id)`	`void`	Delete a video tag from catalog
`SetVideoTagProperty(long tag_id, string property_name, string value)`	`void`	Update tag property (Name, Color, TagParentID, Link, Description)
`GetTagsForVideos(long[] selected_videos)`	`TagInstance[]`	Get tags for selected videos
`RemoveTagsFromVideo(long TagInstanceID)`	`bool`	Remove a tag from a video
`GetVideoTagUse(int tag_id)`	`long`	Get number of uses for a tag

Thumbnail Tags¶

Method	Returns	Description
`GetAllThumbnailTags()`	`Tag[]`	Get all thumbnail tags
`TagThumbs(long[] thumb_list, string entered_keyword_string)`	`int`	Add tag(s) to thumbnails
`DeleteThumbTagFromCatalog(int tag_id)`	`void`	Delete a thumbnail tag
`GetTagsForThumbs(long[] selected_thumbs)`	`TagInstance[]`	Get tags for selected thumbnails
`RemoveTagsFromThumbnails(long TagInstanceID)`	`bool`	Remove a tag from thumbnails
`GetThumbTagUse(int tag_id)`	`long`	Get number of uses for a thumbnail tag

Tag Groups¶

Method	Returns	Description
`CreateTagGroup(string name)`	`long`	Create a new tag group
`DeleteTagGroup(long group_id)`	`void`	Delete a tag group
`RenameTagGroup(long group_id, string new_name)`	`void`	Rename a tag group
`GetAllTagGroups()`	`TagGroup[]`	Get all tag groups
`AddVideoTagToGroup(long video_tag_id, long group_id)`	`void`	Add video tag to group
`RemoveVideoTagFromGroup(long video_tag_id, long group_id)`	`void`	Remove video tag from group
`GetVideoTagsInGroup(long group_id)`	`Tag[]`	Get video tags in a group
`GetThumbnailTagsInGroup(long group_id)`	`Tag[]`	Get thumbnail tags in a group
`GetGroupsForVideoTag(long video_tag_id)`	`TagGroup[]`	Get groups containing a tag

Actor Operations¶

Actor Management¶

Method	Returns	Description
`AddActorToDB(Actor actor)`	`int`	Add a new actor. Returns actor ID.
`GetActor(int actor_id)`	`Actor`	Get actor by ID
`UpdateActor(Actor actor)`	`void`	Update actor properties
`DeleteActor(int actor_id)`	`void`	Delete an actor
`IsActorUsed(int actor_id)`	`bool`	Check if actor is in any video
`GetNofActors()`	`long`	Get total number of actors

Actor Search¶

Method	Returns	Description
`GetActors(string[] tag_filter, string surename_filter, string lastname_filter, bool skip_image_data)`	`Actor[]`	Get actors with filters
`SearchActors(ActorQuery actor_query, bool skip_image_data)`	`Actor[]`	Search actors with query
`SearchActorsFromString(string search_string)`	`Actor[]`	Search actors by text
`GetActorsForVideo(long video_file_id, bool skip_image_data)`	`Actor[]`	Get actors for a video
`GetCast(long[] video_list)`	`Actor[]`	Get cast for multiple videos

Actor-Video Relationships¶

Method	Returns	Description
`AddActorToVideo(long video_file_id, long actor_id)`	`void`	Add actor to video cast
`RemoveActorFromVideo(long video_file_id, long actor_id)`	`void`	Remove actor from video cast

Actor Tags¶

Method	Returns	Description
`GetAllActorTags()`	`Tag[]`	Get all actor tags
`GetActorTags(long actor_id)`	`TagInstance[]`	Get tags for an actor
`CreateActorTag(Tag tag)`	`Tag`	Create a new actor tag
`TagActor(long actor_id, string tag_text)`	`void`	Add tag to actor
`AddActorTag(long actor_id, long tag_id)`	`void`	Add existing tag to actor
`DeleteActorTag(long actor_tag_instance_id)`	`void`	Remove tag from actor
`SetActorTagProperty(long tag_id, string property_name, string value)`	`void`	Update actor tag property
`GetActorTagID(string tag_text)`	`int`	Get tag ID by text
`GetActorTagUse(int tag_id)`	`long`	Get number of uses for actor tag

Actor Images¶

Method	Returns	Description
`GetActorPortrait(long actor_id)`	`byte[]`	Get actor portrait (JPEG)
`GetActorCompanionImages(long actor_id)`	`ActorCompanionImage[]`	Get actor companion images
`AddActorCompanionImage(long actor_id, string path, string server_path)`	`long`	Add companion image to actor
`RemoveActorCompanionImage(long companion_image_id)`	`void`	Remove actor companion image

Face Recognition¶

Method	Returns	Description
`SaveActorFaceEmbedding(long actorId, byte[] embeddingData, string sourceType)`	`void`	Save face embedding for actor
`GetActorFaceEmbedding(long actorId)`	`byte[]`	Get face embedding
`GetAllActorEmbeddings()`	`ActorFaceEmbeddingEntry[]`	Get all actor face embeddings
`DeleteActorFaceEmbedding(long actorId)`	`void`	Delete face embedding

Bin (Collection) Operations¶

Method	Returns	Description
`CreateBin(string label, long parent, UInt32 color, VideoQuery smart_bin_query)`	`Bin`	Create a new bin
`GetAllBins()`	`Bin[]`	Get all bins
`GetBinsInBin(long bin_id)`	`Bin[]`	Get child bins
`GetVideosInBin(long bin_id)`	`VideoFileEntry[]`	Get videos in a bin
`AddVideoToBin(long video_file_id, long bin_id)`	`void`	Add video to bin
`RemoveVideoFromBin(long bin_to_remove_from, long video_to_remove)`	`void`	Remove video from bin
`RemoveBin(long bin_to_remove)`	`void`	Delete a bin
`SetBinProperty(long bin_id, string property_name, string value)`	`void`	Set bin property (Parent, Label, Color, Query)
`SetBinQuery(long bin_id, VideoQuery smart_bin_query)`	`void`	Set smart bin query
`GetBinQuery(long bin_id)`	`VideoQuery`	Get smart bin query

Playlist Operations¶

Method	Returns	Description
`CreateVideoPlaylist(string name)`	`long`	Create a new playlist
`GetAllVideoPlaylists()`	`VideoPlaylist[]`	Get all playlists
`DeletePlaylist(long playlist_id)`	`void`	Delete a playlist
`SetClipToPlaylist(long playlist_id, int index, int clip_id)`	`void`	Add clip to playlist at index
`GetPlaylistClip(long playlist_id, int index)`	`VideoClip`	Get clip at index
`GetPlaylistClipIDs(long playlist_id)`	`int[]`	Get all clip IDs in playlist
`RemovePlaylistClip(long playlist_id, int clip_id)`	`void`	Remove clip from playlist

Video Clips¶

Method	Returns	Description
`SetVideoClip(VideoClip clip)`	`int`	Create or update a clip. Returns clip ID.
`GetVideoClip(int clip_id)`	`VideoClip`	Get clip by ID
`DeleteVideoClip(int clip_id)`	`void`	Delete a clip

Companion Images & Covers¶

Method	Returns	Description
`AddCompanionImages(long video_file_id, string[] image_paths)`	`void`	Add multiple companion images
`AddCompanionImage(long video_file_id, string image_path, string server_path)`	`long`	Add companion image, returns ID
`GetVideoCompanionImages(long video_file_id)`	`VideoCompanionImage[]`	Get companion images for video
`GetVideoCompanionImage(long companion_id)`	`VideoCompanionImage`	Get companion image by ID
`GetAllVideoCompanionImages(int limit, bool random)`	`VideoCompanionImage[]`	Get all companion images
`RemoveVideoCompanionImage(long companion_image_id)`	`void`	Remove companion image
`GetCompanionImageID(long video_file_id, string escaped_path)`	`long`	Get companion image ID for path
`UpdateCompanionImagePath(string Source_path, string Destination_path)`	`bool`	Update companion image path
`SetCompanionImagePath(long image_id, string new_path)`	`void`	Set new path for companion image
`GetNofCompanionImages()`	`long`	Get total number of companion images

Covers¶

Method	Returns	Description
`GetAllCoverImages()`	`CoverImage[]`	Get all cover images
`GetCoverImagesForVideo(long video_file_id)`	`CoverImage`	Get cover for video
`SetCoverImages(long video_file_id, long front_cover_id, long back_cover_id)`	`void`	Set front/back covers

Subtitle/Transcription Operations¶

Method	Returns	Description
`SetSubtitle(Subtitle subtitle)`	`long`	Create or update subtitle
`GetSubtitle(long subtitle_id)`	`Subtitle`	Get subtitle by ID
`GetAllSubtitles(long video_id)`	`Subtitle[]`	Get all subtitles for video
`RemoveSubtitle(long subtitle_id)`	`void`	Remove a subtitle
`RemoveSubtitlesFromVideo(long video_id)`	`void`	Remove all subtitles from video
`SearchSubtitlesFromString(string search_string, long video_id)`	`long[]`	Search subtitles for text

Archive Operations¶

Method	Returns	Description
`CreateArchiveMedia(string title, string description, string device_identifier, string device_root)`	`int`	Create archive media
`GetArchive(int archive_id)`	`Archive`	Get archive by ID
`GetArchives()`	`Archive[]`	Get all archives
`UpdateArchiveMedia(int archive_id, string title, string description, string device_identifier, string device_root)`	`void`	Update archive
`DeleteArchive(int archive_id)`	`void`	Delete archive
`ArchiveVideo(long video_file_id, int archive_id)`	`void`	Put video in archive
`GetArchivesForVideo(long video_file_id)`	`int[]`	Get archives containing video

Genre Operations¶

Method	Returns	Description
`GetGenres()`	`VideoGenre[]`	Get all genres
`RenameGenre(string from, string to)`	`void`	Rename a genre

Utility Methods¶

Method	Returns	Description
`GetLastError()`	`string`	Get last error message
`GetSharedRoots()`	`SharedRoots`	Get shared roots configuration
`GetHostingInfo()`	`HostingInfo`	Get server hosting info
`GetAllTagNames()`	`string[]`	Get all tag names

Example¶

var catalog = scripting.GetVideoCatalogService();
var console = scripting.GetConsole();

// Search for videos
var results = catalog.SearchVideosFromString("action");
console.WriteLine($"Found {results.Length} videos");

// Get video details
foreach (var video in results)
{
    console.WriteLine($"Title: {video.Title}");
    console.WriteLine($"Path: {video.FilePath}");

    // Get actors
    var actors = catalog.GetActorsForVideo(video.ID, true);
    foreach (var actor in actors)
    {
        console.WriteLine($"  Actor: {actor.Name}");
    }
}

// Add a tag to a video
catalog.TagVideo(results[0].ID, "favorite");

// Create a playlist
long playlistId = catalog.CreateVideoPlaylist("My Playlist");