Phoenix API

[stuckless]

Download | New Arbitrary Metadata Discussion | Central Fanart Folder Improvements

This thread is for developers wishing to discuss the Phoenix API, request features, etc.

Phoenix API is a set of community driven APIs for extending the STV language.

This API is intended for STV developers, and is of no value on its own. Normally the Phoenix API will be distributed with a plugin, but the latest release will be availbe here for developers wanting to test the latest features.

The API is broken up into serveral sub-categories, FanartAPI, MediaMetadataAPI, UtilAPI. While there may be other Apis listed in the physical jar file, these are the only APIs that have certified for release.

FanartAPI is a set of APis for managing Fanart, such a getting fanart from the Central Fanart Folder for display in the STV.

MediaMetadataAPI is a set of APIs for dealing searching for new metadata/fanart for media items. This api on it's own is simply a stub API and requires an IMetadataSupport implementation in order to provider the actual implementation for Searching and Downloading metadata. Batch Metadata Tools 2.0 will provider an implementation that is compatible with this API.

UtilAPI is a set of APIs for doing some misc stuff such as creating random numbers or shuffling arrays.

Here is a list of the current apis, but see the actual javadoc for information on what each API call does.

FanartAPI
phoenix_api_GetFanartBackground(Object mediaObject) : String
phoenix_api_GetFanartBackgrounds(Object mediaObject) : String[]
phoenix_api_GetFanartBanner(Object mediaObject) : String
phoenix_api_GetFanartBanners(Object mediaObject) : String[]
phoenix_api_GetFanartPoster(Object mediaObject) : String
phoenix_api_GetFanartGenre(Object mediaObject, String genre) : String
phoenix_api_GetFanartGenres(Object mediaObject, String genre) : String[]
phoenix_api_GetFanartActor(Object mediaObject, String actor) : String
phoenix_api_GetFanartActors(Object mediaObject, String actor) : String[]
phoenix_api_GetFanartPosters(Object mediaObject) : String[]
phoenix_api_IsFanartEnabled() : boolean
phoenix_api_SetIsFanartEnabled(boolean value) : void
phoenix_api_GetFanartCentralFolder() : String
phoenix_api_SetFanartCentralFolder(Object folder) : void
phoenix_api_SetFanartBackground(Object mediaObject, Object fanart) : void
phoenix_api_SetFanartBanner(Object mediaObject, Object fanart) : void
phoenix_api_SetFanartPoster(Object mediaObject, Object fanart) : void
phoenix_api_HasFanartPoster(Object mediaObject) : boolean
phoenix_api_HasFanartBackground(Object mediaObject) : boolean
phoenix_api_HasFanartBanner(Object mediaObject) : boolean
phoenix_api_IsMissingFanart(Object mediaObject) : boolean
phoenix_api_GetFanartBackgroundPath(Object mediaObject) : String
phoenix_api_GetFanartBannerPath(Object mediaObject) : String
phoenix_api_GetFanartPosterPath(Object mediaObject) : String
phoenix_api_GetFanartBackgroundPath(Object mediaObject, boolean create) : String
phoenix_api_GetFanartBannerPath(Object mediaObject, boolean create) : String
phoenix_api_GetFanartPosterPath(Object mediaObject, boolean create) : String

MediaMetadataAPI
phoenix_api_GetMetadataValue(Object item, String key) : String
phoenix_api_StartMetadataScan(Object provider, Object[] mediaFiles) : void
phoenix_api_IsMetadataScanRunning() : boolean
phoenix_api_GetMetadataScanComplete() : float
phoenix_api_GetMetadataSearchResults(Object provider, Object mediaFile) : IMetadataSearchResult[]
phoenix_api_GetMetadataSearchResults(Object mediaFile) : IMetadataSearchResult[]
phoenix_api_GetMetadataSearchResultTitle(IMetadataSearchResult result) : String
phoenix_api_GetMetadataSearchResultScore(IMetadataSearchResult result) : float
phoenix_api_GetMetadataSearchResultYear(IMetadataSearchResult result) : String
phoenix_api_GetMetadataSearchResultProviderId(IMetadataSearchResult result) : String
phoenix_api_UpdateMediaFileMetadata(Object mediaFile, IMetadataSearchResult result) : void
phoenix_api_GetInActiveMetadataProviders() : IMetadataProviderInfo[]
phoenix_api_GetActiveMetadataProviders() : IMetadataProviderInfo[]
phoenix_api_GetInstalledMetadataProviders() : IMetadataProviderInfo[]
phoenix_api_IsActiveMetadataProvider(IMetadataProviderInfo pi) : boolean
phoenix_api_IncreaseMetadataProviderPriority(IMetadataProviderInfo pi) : void
phoenix_api_DecreaseMetadataProviderPriority(IMetadataProviderInfo pi) : void
phoenix_api_AddActiveMetadataProvider(IMetadataProviderInfo pi) : void
phoenix_api_RemoveActiveMetadataProvider(IMetadataProviderInfo pi) : void
phoenix_api_GetMetadataProviderId(IMetadataProviderInfo pi) : String
phoenix_api_GetMetadataProviderName(IMetadataProviderInfo pi) : String
phoenix_api_GetMetadataProviderDescription(IMetadataProviderInfo pi) : String
phoenix_api_IsMetadataProviderSupportEnabled() : boolean
phoenix_api_GetMetadataKeys(String type) : String[]
phoenix_api_GetMetadataLabel(String key) : String
phoenix_api_GetMetadataDescription(String key) : String

UtilAPI
phoenix_api_GetRandomNumber(int max) : int
phoenix_api_GetRandomElement(Object[] array) : Object
phoenix_api_Shuffle(Object objects) : Object
phoenix_api_SubArray(Object array, int start, int length) : Object
phoenix_api_SubArray(Object array, int start) : Object
phoenix_api_RunPhoenixDiagnostics(String report) : String
phoenix_api_IsAtLeastVersion(String verToTest, String baseVersion) : boolean
phoenix_api_Equals(Object o1, Object o2) : boolean

ImageAPI
phoenix_api_CreateScaledImage(Object image, int width, int height) : Object
phoenix_api_CreateJustReflection(Object image, float reflectionAlphaStart, float reflectionAlphaEnd) : Object
phoenix_api_CreateReflection(Object image, float reflectionAlphaStart, float reflectionAlphaEnd) : Object
phoenix_api_CreateReflection(Object image) : Object
phoenix_api_CreatePerspective(Object image, double scalex, double shifty) : Object
phoenix_api_CreateRotatedImage(Object image, double theta) : Object
phoenix_api_CreateGradientFill(String imageId, int imgWidth, int imgHeight, float opacityStart, float opacityEnd) : Object
phoenix_api_LoadImages(Object imageArr) : void
phoenix_api_CreateScaledImages(Object imageArr, int w, int h) : void
phoenix_api_CreateImages(String imageTag, Object imageArr, String jsonTransform, boolean overwriteImages) : void
phoenix_api_CreateImage(String id, String tag, Object image, String transform, boolean overwrite) : Object
phoenix_api_CreateImage(Object image, String transform, boolean overwrite) : Object
phoenix_api_CreateImage(String tag, Object image, String transform, boolean overwrite) : Object
phoenix_api_GetImage(Object image, String tag) : Object
phoenix_api_GetImage(String id, String tag) : Object
phoenix_api_RegisterImageTransform(String transform) : void
phoenix_api_RegisterImageTransform(String transform, String id) : void
phoenix_api_RegisterImage(String id, String tag, Object image, String transform, boolean overwrite) : void

[stuckless]

Just an FYI... i've alread been informed that this build 12 is broken... so no point in downloading this right now.

[jaminben]

I was going to say nice job, but I guess that can wait now until you get the next build done

Only joking, it is a very cool addition and makes life so much easier, for me anyway.

Nice job

[jaminben]

I do have a few requests, one of those requests was something you asked if I wanted before in a previous email and I said I didn't need it. Well it turns out I do

Could you make phoenix_api_GetFanartBackgrounds/poster/banner api return smaller images rather than the full size version as these can take quite awhile to appear on screen. It would also be handy if you could keep the original aspect ratio with the returned smaller images

Could you also add a call for season posters and actors. I don't know if this is possible or even the right way to go about it but I would prefer that a season poster got used rather than a general poster. So if I have season images available in my season 4 folder it would use that image and if I didn't then it would default back to the posters folder.

You could also add phoenix_api_GetFanartSeasonPosters and phoenix_api_SetFanartSeasonPoster if you really wanted to and you have the spare time

Many Thanks

Ben

[stuckless]

Originally Posted by jaminben

Could you make phoenix_api_GetFanartBackgrounds/poster/banner api return smaller images rather than the full size version as these can take quite awhile to appear on screen. It would also be handy if you could keep the original aspect ratio with the returned smaller images

I think the way to perhaps handle this would be to introduce a caching/scaling function into the api. ie, phoenix_api_GetScaledImage(image), where scaled images can be scaled and cached. I think more thought will have to go into it.

Could you also add a call for season posters and actors. I don't know if this is possible or even the right way to go about it but I would prefer that a season poster got used rather than a general poster. So if I have season images available in my season 4 folder it would use that image and if I didn't then it would default back to the posters folder.

This exists... as a transparent part of the Api. ie, If you call, GetFanartBackground() with a media file that has SeasonNumber set in its metadata, then it should first try to call TV/Title/Season NN/Backgrounds/ and if that doesn't return anything, then it should try, TV/Title/Backgrounds. If it's not working, then it's a bug.

As for Actor images, I'm not sure that we standardized a way to store those yet... if we have, then I'm unaware.

You could also add phoenix_api_GetFanartSeasonPosters and phoenix_api_SetFanartSeasonPoster if you really wanted to and you have the spare time

Like GetFanartBackground, SetFanartBackgound should also take into account the Season transparently. SetFanartBackground is currently not working anyways, given that the image is cached. So the jury is still out on how SetFanartXXX should work.

[jaminben]

Originally Posted by stuckless

As for Actor images, I'm not sure that we standardized a way to store those yet... if we have, then I'm unaware.

Currently using EP's scraper it gets stored in its own show folder with all the other images for backgrounds, posters etc. This is probably not the most efficient way to go about it as you could have the same actor image stored in several TV show folders. Perhaps a general folder to go along with TV and Movies would be of better use as this folder could then supply both movies and tv shows.

Originally Posted by stuckless

This exists... as a transparent part of the Api. ie, If you call, GetFanartBackground() with a media file that has SeasonNumber set in its metadata, then it should first try to call TV/Title/Season NN/Backgrounds/ and if that doesn't return anything, then it should try, TV/Title/Backgrounds. If it's not working, then it's a bug.

&

Originally Posted by stuckless

Like GetFanartBackground, SetFanartBackgound should also take into account the Season transparently. SetFanartBackground is currently not working anyways, given that the image is cached. So the jury is still out on how SetFanartXXX should work.

I didn't realise it did this. I'll take a look and see if I can work it out.

Originally Posted by stuckless

SetFanartBackground is currently not working anyways, given that the image is cached. So the jury is still out on how SetFanartXXX should work.

It does sort of work, you just have to restart the client machine. Not a major hassle but not as good as changing an image on the fly.

[evilpenguin]

Originally Posted by stuckless

As for Actor images, I'm not sure that we standardized a way to store those yet... if we have, then I'm unaware

Originally Posted by jaminben

Currently using EP's scraper it gets stored in its own show folder with all the other images for backgrounds, posters etc. This is probably not the most efficient way to go about it as you could have the same actor image stored in several TV show folders. Perhaps a general folder to go along with TV and Movies would be of better use as this folder could then supply both movies and tv shows.

The actor images I get from theTVDB are show specific promotional shots of the actors as their characters rather than generic head shots. So it's probably not very practical to use them for general purposes.

[stuckless]

Again, my question is more of "where" are they stored? I know there was some discussion about this earlier, but I didn't see a firm commitment on the "where", but I may have missed the post, I can barely keep up with the rate new things are being decided... I thought I was done adding new metadata fields, then I noticed a few more added

ie,
TV/House/Season 2/Actors/Gregory House/
or
TV/House/Season 2/Actors/Hugh Lauri/
or
TV/House/Season 2/Actors/Gregory House.jpg
or
TV/House/Season 2/Actors/Hugh Lauri.jpg
or
something else? How are the names being delt with? ie, are we scraping them like the titles to remove certain characters?

[jaminben]

Originally Posted by stuckless

Again, my question is more of "where" are they stored? I know there was some discussion about this earlier, but I didn't see a firm commitment on the "where", but I may have missed the post, I can barely keep up with the rate new things are being decided... I thought I was done adding new metadata fields, then I noticed a few more added

ie,
TV/House/Season 2/Actors/Gregory House/
or
TV/House/Season 2/Actors/Hugh Lauri/
or
TV/House/Season 2/Actors/Gregory House.jpg
or
TV/House/Season 2/Actors/Hugh Lauri.jpg
or
something else? How are the names being delt with? ie, are we scraping them like the titles to remove certain characters?

Mine are stored like:

\\MyServer\Fanart\TV\Bones\Actors\David Boreanaz.jpg

However if you had the same actor from other TV shows you would also then have:

\\MyServer\Fanart\TV\Buffy\Actors\David Boreanaz.jpg

So you would end up with the same actor image in two different locations. Maybe a central actor folder would then be best so you don't get duplicates. As EP said this has a downside when TV actors appear in movies and the TV promotional shots then get used instead of movie shots but does that really matter? The whole actor image is a tad OTT and would very rarely get used but none the less is still a nice feature especially if its free.

As for scraping the files and removing characters, I have no idea about this so I'll keep my nose out.

[evilpenguin]

If no one's using Actors, lets ignore them for now.

[jaminben]

Originally Posted by evilpenguin

If no one's using Actors, lets ignore them for now.

Noooo, lets just get it in then forget about it I can't live without the occasional look at Yvonne Strahovski

edit:

Maybe keep it simple and exactly how EP has it setup now and just create a phoenix_api_GetFanartActors to display all the images in that folder. And thats it, no more user interaction just display a scrollable list of images.

[evilpenguin]

Or we could just solve this, and any future ones like it by doing it like this...

phoenix_api_GetFanartGeneric(Object mediaObject, String fanartType) : String
phoenix_api_GetFanartGenerics(Object mediaObject, String fanartType) : String[]

Which could be called like...

phoenix_api_GetFanartGenerics(MediaFile, "Actors")

which would return all jpgs from...

TV\ShowTitle\Actors

Then STV devs and scrapers could expand the pheonix API's as much as they wanted without any extra code.

[jaminben]

Originally Posted by evilpenguin

Then STV devs and scrapers could expand the pheonix API's as much as they wanted without any extra code.

Sounds good to me.

[jaminben]

Originally Posted by stuckless

This exists... as a transparent part of the Api. ie, If you call, GetFanartBackground() with a media file that has SeasonNumber set in its metadata, then it should first try to call TV/Title/Season NN/Backgrounds/ and if that doesn't return anything, then it should try, TV/Title/Backgrounds. If it's not working, then it's a bug.

I've been trying to get this to work but I can't. I have images located in:

\TV\Smallville\Season 8\Backgrounds\
\TV\Smallville\Season 8\Posters\

But it always defaults to:

\TV\Smallville\Backgrounds\
\TV\Smallville\Posters\

Let me know if you need my logs.

I've also been thinking that phoenix_api_GetFanartPosters should also pull in these season posters as well as general posters. This would also mean phoenix_api_SetFanartPoster should be able to differentiate between the two so that if a user were to pick a general poster over a season poster it would use that poster and not the season poster. Obviously this is speculation at the moment as SetFanartPoster doesnt work fully, but I've got my fingers crossed.

[Tiki]

By the way, did anyone ever come up with a batch file or script for moving/copying fanart from the old folder structure to the new one?

I've got a few thousand images between backgrounds and banners and I don't want to manually create all those new folders...

[Tiki]

Would it be possible to add another utility function that would strip out illegal filename characters from a passed string?

Example:

phoenix_api_GetCleanFileNameFromString(String InputString):String

usage:
phoenix_api_GetCleanFileNameFromString("House/garden")
would return "Housegarden"

phoenix_api_GetCleanFileNameFromString("Terminator: The Sarah Connor Chronicles")
would return "Terminator The Sarah Connor Chronicles"

[evilpenguin]

Originally Posted by Tiki

By the way, did anyone ever come up with a batch file or script for moving/copying fanart from the old folder structure to the new one?

I've got a few thousand images between backgrounds and banners and I don't want to manually create all those new folders...

I've got one, but it only works for backgrounds right now. How do you store your banner files, I can mod it and post it tomorrow.

[stuckless]

Originally Posted by Tiki

Would it be possible to add another utility function that would strip out illegal filename characters from a passed string?

I don't this this will be a part of the "core" api since the use of "cleaned" filenames should be transparent to the api. But, that being said, a "clean" function does exist in the api tree today, and it's used to clean the titles. If you have to manually clean your own your own titles, because you are doing your own thing.... then you can use this api

sagex_phoenix_fanart_FanartUtil_createSafeTitle(string)

I don't why you need to call it directly, but if you provide more details, i may be able to some additional ways your ideas could be implemented.

The Phoenix Fanart api is pluggable, so you could, if you wanted to, write an api that looks for fanart in a different location than the new layout. NOt sure why you'd do that, since the scrapers will be using the new layout, but the possibility remains. Currently i've provided implementations; Local Fanart - the default sagetv locations, SageMC Fanart- the SageMC standard way (no banner support), and the new Central Folder Fanart. By default, the new Central Folder Fanart is active, but any of those could be used.

[jaminben]

I've had another idea which is related to TV series, I'm not sure if this has been mentioned before. How about expanding the way Sage handles grouped recordings with an api specificly designed to sort each show into seasons and then episodes.

So the first step would be to find all recordings with more than one show available with the same title. If you had more than one show of the same title you could consider it to be a series. Once its found all these recorded shows the api would sort these into their own series, all Lost's are placed together the same as all Battlestars are, and so on. Then it would use the metadata to sort each show into their own series and lastly each series would contain their respective episodes. They don't have to specificly be recordings but could also be imported recordings. And thats it.

I don't think I've explained myself very well but hopefully you will get what I mean.

[jaminben]

Here's another idea for you. Have you ever experienced "Have you watched blah blah yet?" I reply "Yes" she replies "Can I delete it then" I reply "Well yes if you've watched it". So how about a user oriented log on/watched api.

When a user first switches on their extender/client they are greeted with a log on option, this could be a nice graphic system or a plain text option. Once the user has selected their graphic (logged on) all items that they watch become identified as watched by that user. This could be expanded to say a max of four users and each users watched bar is identified by a color they specify in the log on setup process.

Its just an idea which I could expand on with a few made up screenshots using studio. If your interested then I'll go ahead and do those. Obviously I don't expect you to work on this straight away and have it done by the weekend, after all its just an idea

Ben