Package sage.api

Class MediaFileAPI

java.lang.Object

sage.api.MediaFileAPI

public class MediaFileAPI
extends java.lang.Object

A MediaFile represents a physical file or a group of files that represent the same content. Every MediaFile has an Airing associated with it that describes the metadata information for the content through the use of a Show object. There are also special MediaFiles that represent streams from capture devices directly or other playback hardware such as CD/DVD drives.

SageTV will automatically convert the following types to MediaFile if used for a parameter that requires the MediaFile type:

Airing - if an Airing has an associated MediaFile then it will be used, otherwise the conversion results in null java.io.File - if the specified physical file has an assoicated MediaFile, then it will be used

Constructor Summary

Constructors

Constructor	Description
MediaFileAPI()

Method Summary

Modifier and Type	Method	Description
sage.MediaFile	AddMediaFile(java.io.File File, java.lang.String NamePrefix)	Adds a new MediaFile to the database.
boolean	AutorotatePictureFile(sage.MediaFile MediaFile)	Automatically rotates the specified picture file according to the orientation set in the EXIF data.
boolean	CanAutorotatePictureFile(sage.MediaFile MediaFile)	Returns true if the specified picture file can be autorotated and is currently not in that autorotated position
void	CopyToLocalFile(sage.MediaFile MediaFile, java.io.File LocalFile)	Downloads the specified MediaFile from the SageTV server and saves it as the specified LocalFile.
sage.MediaFile	CreateTempMediaFile(java.lang.String FilePath)	Creates a temporary MediaFile object which can be used for playback later.
boolean	DeleteFile(sage.MediaFile MediaFile)	Deletes the files that correspond to this MediaFile from disk and also deletes the MediaFile object from the database.
boolean	DeleteFileWithoutPrejudice(sage.MediaFile MediaFile)	Deletes the files that correspond to this MediaFile from disk and also deletes the MediaFile object from the database.
boolean	FlipPictureFile(sage.MediaFile MediaFile, boolean Horizontal)	Performs a lossless flip of the specified JPEG picture file.
boolean	GenerateThumbnail(sage.MediaFile MediaFile, float Time, int Width, int Height, java.io.File File)	Generates a thumbnail for the specified MediaFile at the requested offset time in the file using the desired width & height.
sage.Album	GetAlbumForFile(sage.MediaFile MediaFile)	Gets the Album object that corresponds to this MediaFile.
long	GetDurationForSegment(sage.MediaFile MediaFile, int SegmentNumber)	Returns the duration in milliseconds for the specified segment number in this MediaFile.
long	GetEndForSegment(sage.MediaFile MediaFile, int SegmentNumber)	Gets the ending time for a specified segment number in this MediaFile.
long	GetFileDuration(sage.MediaFile MediaFile)	Returns the total duration of the content in this MediaFile
long	GetFileEndTime(sage.MediaFile MediaFile)	Returns the ending time for the content in ths specified MediaFile.
java.io.File	GetFileForSegment(sage.MediaFile MediaFile, int SegmentNumber)	Gets the file that represents the specified segment number in this MediaFile
long	GetFileStartTime(sage.MediaFile MediaFile)	Returns the starting time for the content in ths specified MediaFile.
sage.MetaImage	GetFullImage(sage.MediaFile MediaFile)	Returns the MetaImage object which represents the picture file for this MediaFile.
sage.Airing	GetMediaFileAiring(sage.MediaFile MediaFile)	Gets the Airing object that represents the content metadata for this MediaFile
java.lang.String	GetMediaFileEncoding(sage.MediaFile MediaFile)	Gets the encoding that was used to record this file.
sage.MediaFile	GetMediaFileForFilePath(java.io.File FilePath)	Returns the MediaFile from the database that corresponds to a specified file on disk
sage.MediaFile	GetMediaFileForID(int id)	Returns the MediaFile object that corresponds to the passed in ID.
java.lang.String	GetMediaFileFormatDescription(sage.MediaFile MediaFile)	Returns a string that provides a description of this MediaFile's format, i.e.
int	GetMediaFileID(sage.MediaFile MediaFile)	Returns the unique ID used to identify this MediaFile.
java.lang.String	GetMediaFileMetadata(sage.MediaFile MediaFile, java.lang.String Name)	Returns a string for the corresponding metadata property in the MediaFile's format.
java.util.Properties	GetMediaFileMetadataProperties(sage.MediaFile MediaFile)	Returns a java.util.Properties object that contains all of the metadata properties for a MediaFile object.
java.lang.String	GetMediaFileRelativePath(sage.MediaFile MediaFile)	Returns the path of this MediaFile object relative to the root of the import directory it is in.
sage.MediaFile[]	GetMediaFiles()	Returns all of the MediaFile objects in the database.
sage.MediaFile[]	GetMediaFiles(java.lang.String MediaMask)	Returns all of the MediaFile objects in the database The content it references must also match one of the media types specified in the MediaMask.
java.lang.String	GetMediaTitle(sage.MediaFile MediaFile)	Returns the title for the specified MediaFile object
int	GetNumberOfSegments(sage.MediaFile MediaFile)	Returns the number of segments in ths specified MediaFile.
java.io.File	GetParentDirectory(sage.MediaFile MediaFile)	Gets the directory that the files for this MediaFile are in.
java.io.File[]	GetSegmentFiles(sage.MediaFile MediaFile)	Returns the list of files that make up the specified MediaFile object.
long	GetSize(sage.MediaFile MediaFile)	Gets the total size in bytes of the files on disk that represent this MediaFile
long	GetStartForSegment(sage.MediaFile MediaFile, int SegmentNumber)	Gets the starting time for a specified segment number in this MediaFile.
long[][]	GetStartTimesForSegments(sage.MediaFile MediaFile)	Returns a list of all of the start times of the segments in the specified MediaFile
sage.MetaImage	GetThumbnail(sage.MediaFile MediaFile)	Gets the representative thumbnail image which should be used for iconic display of this MediaFile.
boolean	HasAnyThumbnail(sage.MediaFile MediaFile)	Returns true if this MediaFile object has a thumbnail representation of it.
boolean	HasSpecificThumbnail(sage.MediaFile MediaFile)	Returns true if this MediaFile object has a thumbnail for it that is unique to the content itself.
boolean	IsBluRay(sage.MediaFile MediaFile)	Returns true if this MediaFile represents BluRay content.
boolean	IsCompleteRecording(sage.MediaFile MediaFile)	Returns true if SageTV considers this MediaFile a 'complete' recording.
boolean	IsDVD(sage.MediaFile MediaFile)	Returns true if this MediaFile represents DVD content.
boolean	IsDVDDrive(sage.MediaFile MediaFile)	Returns true if this MediaFile represents the physical DVD drive in the system.
boolean	IsFileCurrentlyRecording(sage.MediaFile MediaFile)	Returns true if this MediaFile is currently in the process of recording.
boolean	IsLibraryFile(sage.MediaFile MediaFile)	Returns true if the specified MediaFile has been either imported using a library path or if this is a television recording that has had the 'Move to Library' operation performed on it.
boolean	IsLocalFile(sage.MediaFile MediaFile)	Returns true if the specified MediaFile is local to this system (i.e.
boolean	IsMediaFileObject(java.lang.Object Object)	Returns true if the specified object is a MediaFile object.
boolean	IsMusicFile(sage.MediaFile MediaFile)	Returns true if this MediaFile's content is audio only.
boolean	IsPictureFile(sage.MediaFile MediaFile)	Returns true if this MediaFile's content represents a picture file
boolean	IsThumbnailLoaded(sage.MediaFile MediaFile)	Checks whether the passed thumbnail for the specified MediaFile is loaded into system memory or into the VRAM cache of the corresponding UI making the call.
boolean	IsTVFile(sage.MediaFile MediaFile)	Returns true if this MediaFile represents recorded television content
boolean	IsVideoFile(sage.MediaFile MediaFile)	Returns true if this MediaFile's content is an audio/video or video file (this will be false for DVD/BluRay content)
void	MoveFileToLibrary(sage.MediaFile MediaFile)	Marks a MediaFile object as being 'Moved to Library' which means the IsLibraryFile() call will now return true.
void	MoveTVFileOutOfLibrary(sage.MediaFile MediaFile)	Un-marks a MediaFile object as being 'Moved to Library' which means the IsLibraryFile() call will no longer return true.
void	RegeneratePictureThumbnail(sage.MediaFile MediaFile)	Regenerates the thumbnail associated with the specified picture file.
boolean	RotatePictureFile(sage.MediaFile MediaFile, int Degrees)	Performs a lossless rotation of the specified JPEG picture file (90, 180 or 270 degrees).
boolean	SetMediaFileAiring(sage.MediaFile MediaFile, sage.Airing Airing)	Sets a link between a MediaFile object which represents a file(s) on disk and an Airing object which represents metadata about the content.
void	SetMediaFileMetadata(sage.MediaFile MediaFile, java.lang.String Name, java.lang.String Value)	Sets the corresponding metadata property in the MediaFile's format.
boolean	SetMediaFileShow(sage.MediaFile MediaFile, sage.Show Show)	Sets a link between a MediaFile object which represents a file(s) on disk and a Show object which represents metadata about the content.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MediaFileAPI

public MediaFileAPI()

Method Detail

GetMediaFiles

public sage.MediaFile[] GetMediaFiles()

Returns all of the MediaFile objects in the database.

Returns:

a list of all of the MediaFile objects in the database

GetMediaFiles

public sage.MediaFile[] GetMediaFiles(java.lang.String MediaMask)

Returns all of the MediaFile objects in the database The content it references must also match one of the media types specified in the MediaMask. There's also an additional supported type of 'L' which indicates files that pass IsLibraryFile()

Parameters:

MediaMask - string specifying what content types to search (i.e. "TM" for TV & Music, 'T'=TV, 'M'=Music, 'V'=Video, 'D'=DVD, 'P'=Pictures, 'B'=BluRay)

Returns:

a list of all of the MediaFile objects in the database that match the mask

Since:

6.4

AddMediaFile

public sage.MediaFile AddMediaFile(java.io.File File,
                                   java.lang.String NamePrefix)

Adds a new MediaFile to the database. This file will remain in the database until it is manually removed by the user or when the file no longer exists.

Parameters:

File - the file path for the new MediaFile

NamePrefix - the 'prefix' to prepend to the name of this media file for hierarchical purposes (i.e. the subdirectory that the file is in relative to the import root)

Returns:

the newly added MediaFile object

CreateTempMediaFile

public sage.MediaFile CreateTempMediaFile(java.lang.String FilePath)

Creates a temporary MediaFile object which can be used for playback later. This will not be added into the database; but any metadata that is attached to this MediaFile object will be put in the database until the next cleanup process occurs.

Parameters:

FilePath - the file path for the temporary MediaFile (can also be an smb:// URL)

Returns:

the newly created temporary MediaFile object or null if it can't properly resolve the path to a file

Since:

6.6

SetMediaFileAiring

public boolean SetMediaFileAiring(sage.MediaFile MediaFile,
                                  sage.Airing Airing)

Sets a link between a MediaFile object which represents a file(s) on disk and an Airing object which represents metadata about the content. This is a way to link content information with media.

Parameters:

MediaFile - the MediaFile object to set the content information for

Airing - the Airing object that should be the content metadata pointer for this MediaFile

Returns:

true if the operation succeeded, false otherwise; this operation will fail if the Airing is already linked to another MediaFile

SetMediaFileShow

public boolean SetMediaFileShow(sage.MediaFile MediaFile,
                                sage.Show Show)

Sets a link between a MediaFile object which represents a file(s) on disk and a Show object which represents metadata about the content. This is a way to link content information with media. This will create a new Airing representing this Show and add it to the database. Then that new Airing is linked with this MediaFile (just like it is in SetMediaFileAiring()

Parameters:

MediaFile - the MediaFile object to set the content information for

Show - the Show object that should be the content information for this MediaFile

Returns:

true if the operation succeeded, false otherwise; this operation will fail only if one of the arguments is null

GetMediaFileForFilePath

public sage.MediaFile GetMediaFileForFilePath(java.io.File FilePath)

Returns the MediaFile from the database that corresponds to a specified file on disk

Parameters:

FilePath - the file path to find the corresponding MediaFile for

Returns:

the MediaFile for the corresponding file path, or null if there is no corresponding MediaFile

IsLocalFile

public boolean IsLocalFile(sage.MediaFile MediaFile)

Returns true if the specified MediaFile is local to this system (i.e. doesn't need to be streamed from a server)

Parameters:

MediaFile - the MediaFile object

Returns:

true if the specified MediaFile is local to this system (i.e. doesn't need to be streamed from a server), false otherwise

IsLibraryFile

public boolean IsLibraryFile(sage.MediaFile MediaFile)

Returns true if the specified MediaFile has been either imported using a library path or if this is a television recording that has had the 'Move to Library' operation performed on it.

Parameters:

MediaFile - the MediaFile object

Returns:

true if the specified MediaFile has been either imported using a library path or if this is a television recording that has had the 'Move to Library' operation performed on it; false otherwise

IsCompleteRecording

public boolean IsCompleteRecording(sage.MediaFile MediaFile)

Returns true if SageTV considers this MediaFile a 'complete' recording. The rules behind this are somewhat complex, but the intended purpose is that a 'complete' recording is one that should be presented in the list of recordings to a user.

Parameters:

MediaFile - the MediaFile object

Returns:

true if SageTV considers this MediaFile a 'complete' recording

IsDVD

public boolean IsDVD(sage.MediaFile MediaFile)

Returns true if this MediaFile represents DVD content. This can be either a DVD drive or a ripped DVD.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile represents DVD content, false otherwise

IsBluRay

public boolean IsBluRay(sage.MediaFile MediaFile)

Returns true if this MediaFile represents BluRay content.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile represents BluRay content, false otherwise

Since:

6.6

IsDVDDrive

public boolean IsDVDDrive(sage.MediaFile MediaFile)

Returns true if this MediaFile represents the physical DVD drive in the system. Use this MediaFile to playback DVDs from an optical drive.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile represents the physical DVD drive in the system, false otherwise

IsMusicFile

public boolean IsMusicFile(sage.MediaFile MediaFile)

Returns true if this MediaFile's content is audio only.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile's content is audio only, false otherwise

IsVideoFile

public boolean IsVideoFile(sage.MediaFile MediaFile)

Returns true if this MediaFile's content is an audio/video or video file (this will be false for DVD/BluRay content)

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile's content is an audio/video or video file (this will be false for DVD/BluRay content), false otherwise

IsPictureFile

public boolean IsPictureFile(sage.MediaFile MediaFile)

Returns true if this MediaFile's content represents a picture file

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile's content represents a picture file, false otherwise

IsTVFile

public boolean IsTVFile(sage.MediaFile MediaFile)

Returns true if this MediaFile represents recorded television content

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile represents recorded television content, false otherwise

GetSegmentFiles

public java.io.File[] GetSegmentFiles(sage.MediaFile MediaFile)

Returns the list of files that make up the specified MediaFile object. A MediaFile object can represent more than one physical file on disk. This occurs when a recording of a television show is not contiguous; this can happen for various reasons including the user changing the channel or restarting the system.

Parameters:

MediaFile - the MediaFile object

Returns:

the list of files that make up this MediaFile object

GetMediaTitle

public java.lang.String GetMediaTitle(sage.MediaFile MediaFile)

Returns the title for the specified MediaFile object

Parameters:

MediaFile - the MediaFile object

Returns:

the title for the specified MediaFile object

GetMediaFileRelativePath

public java.lang.String GetMediaFileRelativePath(sage.MediaFile MediaFile)

Returns the path of this MediaFile object relative to the root of the import directory it is in.

Parameters:

MediaFile - the MediaFile object

Returns:

the path of this MediaFile object relative to the root of the import directory it is in

Since:

7.0

GetParentDirectory

public java.io.File GetParentDirectory(sage.MediaFile MediaFile)

Gets the directory that the files for this MediaFile are in.

Parameters:

MediaFile - the MediaFile object

Returns:

the directory that the files for this MediaFile are in

GetSize

public long GetSize(sage.MediaFile MediaFile)

Gets the total size in bytes of the files on disk that represent this MediaFile

Parameters:

MediaFile - the MediaFile object

Returns:

the total size in bytes of the files on disk that represent this MediaFile

GetFullImage

public sage.MetaImage GetFullImage(sage.MediaFile MediaFile)

Returns the MetaImage object which represents the picture file for this MediaFile. If the specified MediaFile is not a picture file, then null is returned

Parameters:

MediaFile - the MediaFile object

Returns:

the MetaImage object which represents the picture file for this MediaFile. If the specified MediaFile is not a picture file, then null is returned

GenerateThumbnail

public boolean GenerateThumbnail(sage.MediaFile MediaFile,
                                 float Time,
                                 int Width,
                                 int Height,
                                 java.io.File File)

Generates a thumbnail for the specified MediaFile at the requested offset time in the file using the desired width & height. The resulting thumbnail will be saved to the specified file. This call DOES NOT need to be used for GetThumbnail to work properly; this API call is intended as an extra for developers who want additional thumbnails beyond the one that is normally auto-generated for MediaFiles. This API call will not return until the generation of the thumbnail is complete. If both width & height are zero, then the size will be determined automatically to match the aspect ratio of the video (the largest dimension will match what SageTV uses internally for thumbnail sizes). If only one of width or height is zero, then the other dimension will be determined automatically to match the aspect ratio of the video.

Parameters:

MediaFile - the MediaFile object, must be a Video file (no BluRays or DVDs)

Time - the offset time in seconds at which the thumbnail should be generated (relative to the start of the file), while fractional seconds are supported, accuracy cannot be guaranteed

Width - the width in pixels of the desired thumbnail

Height - the height in pixels of the desired thumbnail

File - the file path to save the thumbnail to

Returns:

true if the generation succeeded, false if it failed

Since:

7.1

GetThumbnail

public sage.MetaImage GetThumbnail(sage.MediaFile MediaFile)

Gets the representative thumbnail image which should be used for iconic display of this MediaFile. For picture files, this will be a thumbnail image. For music files it will be the album art. For any other files it'll be the thumbnail for the file if one exists, otherwise it'll be the channel logo for the file. If none of those exist then null is returned.

Parameters:

MediaFile - the MediaFile object

Returns:

the representative thumbnail image which should be used for iconic display of this MediaFile

IsThumbnailLoaded

public boolean IsThumbnailLoaded(sage.MediaFile MediaFile)

Checks whether the passed thumbnail for the specified MediaFile is loaded into system memory or into the VRAM cache of the corresponding UI making the call.

Parameters:

MediaFile - the MediaFile object

Returns:

true if the thumbnail image for the specified MediaFile is loaded into system memory or the calling UI's VRAM, false otherwise

Since:

6.1

HasSpecificThumbnail

public boolean HasSpecificThumbnail(sage.MediaFile MediaFile)

Returns true if this MediaFile object has a thumbnail for it that is unique to the content itself. This is true for any music file with album art or any other MediaFile that has another file on disk which contains the representative thumbnail.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile object has a thumbnail for it that is unique to the content itself, false otherwise

HasAnyThumbnail

public boolean HasAnyThumbnail(sage.MediaFile MediaFile)

Returns true if this MediaFile object has a thumbnail representation of it. If this is true, then GetThumbnail() will not return null.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile object has a thumbnail representation of it, false otherwise

IsFileCurrentlyRecording

public boolean IsFileCurrentlyRecording(sage.MediaFile MediaFile)

Returns true if this MediaFile is currently in the process of recording.

Parameters:

MediaFile - the MediaFile object

Returns:

true if this MediaFile is currently in the process of recording, false otherwise

DeleteFile

public boolean DeleteFile(sage.MediaFile MediaFile)

Deletes the files that correspond to this MediaFile from disk and also deletes the MediaFile object from the database. NOTE: This actually delete the files from the disk. This has a slightly different effect on Intelligent Recording versus the DeleteFileWithoutPrejudice()

Parameters:

MediaFile - the MediaFile object to delete

Returns:

true if the deletion succeeded, false otherwise. A deletion can fail because the file is currently being recorded or watched or because the native filesystem is unable to delete the file.

DeleteFileWithoutPrejudice

public boolean DeleteFileWithoutPrejudice(sage.MediaFile MediaFile)

Deletes the files that correspond to this MediaFile from disk and also deletes the MediaFile object from the database. NOTE: This actually delete the files from the disk. This has a slightly different effect on Intelligent Recording versus DeleteFile(). DeleteFileWithoutPrejudice should be used when the file was incorrectly recorded or in other cases where this deletion decision should have no effect on intelligent recording.

Parameters:

MediaFile - the MediaFile object to delete

Returns:

true if the deletion succeeded, false otherwise. A deletion can fail because the file is currently being recorded or watched or because the native filesystem is unable to delete the file.

GetFileDuration

public long GetFileDuration(sage.MediaFile MediaFile)

Returns the total duration of the content in this MediaFile

Parameters:

MediaFile - the MediaFile object

Returns:

the total duration in milliseconds of the content in the specified MediaFile

GetFileStartTime

public long GetFileStartTime(sage.MediaFile MediaFile)

Returns the starting time for the content in ths specified MediaFile. This corresponds to when the file's recording started or the timestamp on the file itself. See java.lang.System.currentTimeMillis() for information on the time units.

Parameters:

MediaFile - the MediaFile object

Returns:

the starting time for the content in the specified MediaFile

GetFileEndTime

public long GetFileEndTime(sage.MediaFile MediaFile)

Returns the ending time for the content in ths specified MediaFile. This corresponds to when the file's recording ended or the timestamp on the file itself plus the file's duration. See java.lang.System.currentTimeMillis() for information on the time units.

Parameters:

MediaFile - the MediaFile object

Returns:

the ending time for the content in the specified MediaFile

CopyToLocalFile

public void CopyToLocalFile(sage.MediaFile MediaFile,
                            java.io.File LocalFile)

Downloads the specified MediaFile from the SageTV server and saves it as the specified LocalFile. This call should only be made by SageTV Client.

Parameters:

MediaFile - the MediaFile object to download a copy of

LocalFile - the destination file to store the MediaFile as on the local filesystem

GetDurationForSegment

public long GetDurationForSegment(sage.MediaFile MediaFile,
                                  int SegmentNumber)

Returns the duration in milliseconds for the specified segment number in this MediaFile.

Parameters:

MediaFile - the MediaFile object

SegmentNumber - the 0-based segment number to get the duration of

Returns:

the duration in milliseconds for the specified segment number in this MediaFile

GetEndForSegment

public long GetEndForSegment(sage.MediaFile MediaFile,
                             int SegmentNumber)

Gets the ending time for a specified segment number in this MediaFile.

Parameters:

MediaFile - the MediaFile object

SegmentNumber - the 0-based segment number to get the end time of

Returns:

the ending time for a specified segment number in this MediaFile

GetStartForSegment

public long GetStartForSegment(sage.MediaFile MediaFile,
                               int SegmentNumber)

Gets the starting time for a specified segment number in this MediaFile.

Parameters:

MediaFile - the MediaFile object

SegmentNumber - the 0-based segment number to get the start time of

Returns:

the starting time for a specified segment number in this MediaFile

GetFileForSegment

public java.io.File GetFileForSegment(sage.MediaFile MediaFile,
                                      int SegmentNumber)

Gets the file that represents the specified segment number in this MediaFile

Parameters:

MediaFile - the MediaFile object

SegmentNumber - the 0-based segment number to get the file for

Returns:

the file that represents the specified segment number in this MediaFile

GetNumberOfSegments

public int GetNumberOfSegments(sage.MediaFile MediaFile)

Returns the number of segments in ths specified MediaFile. Each segment corresponds to a different physical file on disk.

Parameters:

MediaFile - the MediaFile object

Returns:

the number of segments in ths specified MediaFile

GetStartTimesForSegments

public long[][] GetStartTimesForSegments(sage.MediaFile MediaFile)

Returns a list of all of the start times of the segments in the specified MediaFile

Parameters:

MediaFile - the MediaFile object

Returns:

a list of all of the start times of the segments in the specified MediaFile

MoveFileToLibrary

public void MoveFileToLibrary(sage.MediaFile MediaFile)

Marks a MediaFile object as being 'Moved to Library' which means the IsLibraryFile() call will now return true. This can be used to help organize the recorded television files.

Parameters:

MediaFile - the MediaFile ojbect

MoveTVFileOutOfLibrary

public void MoveTVFileOutOfLibrary(sage.MediaFile MediaFile)

Un-marks a MediaFile object as being 'Moved to Library' which means the IsLibraryFile() call will no longer return true. This can only be used on recorded television files and has the opposite effect of MoveFileToLibrary()

Parameters:

MediaFile - the MediaFile ojbect

IsMediaFileObject

public boolean IsMediaFileObject(java.lang.Object Object)

Returns true if the specified object is a MediaFile object. No automatic type conversion will be performed on the argument. This will return false if the argument is a MediaFile object, BUT that object no longer exists in the SageTV database.

Parameters:

Object - the object to test to see if it is a MediaFile object

Returns:

true if the argument is a MediaFile object, false otherwise

GetAlbumForFile

public sage.Album GetAlbumForFile(sage.MediaFile MediaFile)

Gets the Album object that corresponds to this MediaFile. This only returns a useful object if the argument is a music file.

Parameters:

MediaFile - the MediaFile object

Returns:

the Album object that corresponds to this MediaFile

GetMediaFileEncoding

public java.lang.String GetMediaFileEncoding(sage.MediaFile MediaFile)

Gets the encoding that was used to record this file. This will only return something useful for recorded television files.

Parameters:

MediaFile - the MediaFile object

Returns:

the encoding that was used to record this file

GetMediaFileAiring

public sage.Airing GetMediaFileAiring(sage.MediaFile MediaFile)

Gets the Airing object that represents the content metadata for this MediaFile

Parameters:

MediaFile - the MediaFile object

Returns:

the Airing object that represents the content metadata for this MediaFile

GetMediaFileID

public int GetMediaFileID(sage.MediaFile MediaFile)

Returns the unique ID used to identify this MediaFile. Can get used later on a call to GetMediaFileForID()

Parameters:

MediaFile - the MediaFileobject

Returns:

the unique ID used to identify this MediaFile

GetMediaFileForID

public sage.MediaFile GetMediaFileForID(int id)

Returns the MediaFile object that corresponds to the passed in ID. The ID should have been obtained from a call to GetMediaFileID()

Parameters:

id - the id of the MediaFile object to get

Returns:

the MediaFile object that corresponds to the passed in ID

GetMediaFileFormatDescription

public java.lang.String GetMediaFileFormatDescription(sage.MediaFile MediaFile)

Returns a string that provides a description of this MediaFile's format, i.e. MPEG2-PS[MPEG2-Video/2.0Mbps 4:3 480i@30fps, MP2/192kbps@48kHz]

Parameters:

MediaFile - the MediaFile object

Returns:

a string that provides a description of this MediaFile's format

Since:

5.1

GetMediaFileMetadata

public java.lang.String GetMediaFileMetadata(sage.MediaFile MediaFile,
                                             java.lang.String Name)

Returns a string for the corresponding metadata property in the MediaFile's format. These are set during format detection/import. Names set in the property "custom_metadata_properties" (which is a semicolon/comma delimited list) will be available; as well as all standard SageTV metadata fields and details on format information. These include Title, Description, EpisodeName, Track, Duration, Genre, Language, RunningTime, Rated, ParentalRating, PartNumber, TotalParts, HDTV, CC, Stereo, SAP, Subtitled, 3D, DD5.1, Dolby, Letterbox, Live, New, Widescreen, Surround, Dubbed, Taped, Premiere, SeasonPremiere, SeriesPremiere, ChannelPremiere, SeasonFinale, SeriesFinale, SeasonNumber, EpisodeNumber, ExternalID, Album, Year, OriginalAirDate, ExtendedRatings, Misc, All "Role" Names, Format.Video.Codec, Format.Video.Resolution, Format.Video.Aspect, Format.Video.Bitrate, Format.Video.Width, Format.Video.Height, Format.Video.FPS, Format.Video.Interlaced, Format.Video.Progressive, Format.Video.Index, Format.Video.ID, Format.Audio.NumStreams, Format.Audio[.#].Codec, Format.Audio[.#].Channels, Format.Audio[.#].Language, Format.Audio[.#].SampleRate, Format.Audio[.#].BitsPerSample, Format.Audio[.#].Index, Format.Audio[.#].ID, Format.Subtitle.NumStreams, Format.Subtitle[.#].Codec, Format.Subtitle[.#].Language, Format.Subtitle[.#].Index, Format.Subtitle[.#].ID, Format.Subtitle[.#].Forced, Format.Container and Picture.Resolution

Parameters:

MediaFile - the MediaFile object

Name - the name of the property to get

Returns:

a string corresponding to the metadata property value, or the emptry string if it is undefined

Since:

6.6

GetMediaFileMetadataProperties

public java.util.Properties GetMediaFileMetadataProperties(sage.MediaFile MediaFile)

Returns a java.util.Properties object that contains all of the metadata properties for a MediaFile object. This will only include properties that can be modified (i.e. no format information is included). These properties will include all the standard database fields, as well as any custom metadata properties that were set for this MediaFile object. See SetMediaFileMetadata() and GetMediaFileMetadata() for more details on those properties.

Parameters:

MediaFile - the MediaFile object

Returns:

a java.util.Properties object with all the metadata properties for this MediaFile, this is a copy and is safe to modify

Since:

7.1

SetMediaFileMetadata

public void SetMediaFileMetadata(sage.MediaFile MediaFile,
                                 java.lang.String Name,
                                 java.lang.String Value)

Sets the corresponding metadata property in the MediaFile's format. These are set in the database and are also exported to the corresponding .properties file for that MediaFile. When it exports it will append these updates to the .properties file. It will also update the property "custom_metadata_properties" (which is a semicolon/comma delimited list) which tracks the extra metadata properties that should be retained. Usage of any of the following names will update the corresponding Airing/Show object for the MediaFile as well: Title, Description, EpisodeName, Track, Duration, Genre, Language, RunningTime, Rated, ParentalRating, PartNumber, TotalParts, HDTV, CC, Stereo, SAP, Subtitled, 3D, DD5.1, Dolby, Letterbox, Live, New, Widescreen, Surround, Dubbed, Taped, SeasonNumber, EpisodeNumber Premiere, SeasonPremiere, SeriesPremiere, ChannelPremiere, SeasonFinale, SeriesFinale, ExternalID, Album, Year, OriginalAirDate, ExtendedRatings, Misc and All "Role" Names

Parameters:

MediaFile - the MediaFile object

Name - the name of the property to set

Value - the value of the property to set

Since:

6.6

RotatePictureFile

public boolean RotatePictureFile(sage.MediaFile MediaFile,
                                 int Degrees)

Performs a lossless rotation of the specified JPEG picture file (90, 180 or 270 degrees). This will modify the file that is stored on disk.

Parameters:

MediaFile - the MediaFile object

Degrees - the number of degress to rotate the picture in the clockwise direction, can be a positive or negative value and must be a multiple of 90

Returns:

true if the rotation was successful, false otherwise

Since:

5.1

FlipPictureFile

public boolean FlipPictureFile(sage.MediaFile MediaFile,
                               boolean Horizontal)

Performs a lossless flip of the specified JPEG picture file. This will modify the file that is stored on disk.

Parameters:

MediaFile - the MediaFile object

Horizontal - true if it should be flipped horizontally (i.e. around a vertical axis), false if it should be flipped vertically (i.e. around a horizontal axis)

Returns:

true if the flip was successful, false otherwise

Since:

5.1

CanAutorotatePictureFile

public boolean CanAutorotatePictureFile(sage.MediaFile MediaFile)

Returns true if the specified picture file can be autorotated and is currently not in that autorotated position

Parameters:

MediaFile - the MediaFile object

Returns:

true if the specified picture file can be autorotated and is currently not in that autorotated position

Since:

6.4

AutorotatePictureFile

public boolean AutorotatePictureFile(sage.MediaFile MediaFile)

Automatically rotates the specified picture file according to the orientation set in the EXIF data.

Parameters:

MediaFile - the MediaFile object that represents the picture

Returns:

true if the automatic rotation succeeded, false otherwise

Since:

6.4

RegeneratePictureThumbnail

public void RegeneratePictureThumbnail(sage.MediaFile MediaFile)

Regenerates the thumbnail associated with the specified picture file. Sometimes the rotation may be mis-aligned from the thumbnail and this allows a way to repair that.

Parameters:

MediaFile - the MediaFile object

Since:

6.4