Library: Remote APIs for SageTV

[shadeblue.com]

Originally Posted by stuckless

The problem with jar services is that you'll need to restart sagetv in order to pick up the jar. Out of the box, the services model in the api doesn't support dynamic services in jars because it would have required that I build a new classloader and then manage that, which was something that I didn't want to do.

But, if you are ok with having to restart sagetv once a jar is deployed, then you can still use js services and call your jar file. ie, your .js file simply defines the service and then calls into the code that is in the jar. the js services has access to ALL classes that is in the classpath.

So, if you have a shadeblue.jar then you can use that in the js services like...

function ShadyService(myobject) {
    var mystuf = new Packages.com.shadeblue.MyCustomJavaObject();
    return mystuff.process(myobject);
}

The above assumes that you have a java call MyCustomJavaObject with a method called pocess();

Keep in mind that if you are using javascript services, then it will require java 6, since I'm just leveraging the scripting engine in java 6.

Thanks for the info, that should work for my needs!
-SB

[KJake]

I'm new to the API and this library entirely. I got the idea that I could write some new webpages using JSON queries. Come to find out, this Library provides the very back-end that I needed

Follow forum member LehighBri requested that I share my beginnings so that they could write some pages too. I figured that others might benefit from this example, as incomplete as it is.

The example is fairly simple. It pages through your TV Recordings. It would have been nice if I added selects to allow changing the MediaFilter or the results per page, but where's the fun in that??

Instructions:
1) Install the sagex-api library under Jetty (http://forums.sagetv.com/forums/down...do=file&id=255)
2) Place the contents of my zip under the jetty folder so that you end up with SageTV/jetty/static/*files*

This will make the page display as the main page for your Jetty installation, so you can go to http://your_jetty_ip:your_jetty_port to view the example page.

All the heavy lifting is handled client-side with jQuery - documentation on the built-in functions can be found here: http://docs.jquery.com
I did use some additional plugins to make things smoother, just google for the docs on those.

[edit]
I did notice an irritating hang in Chrome when the ajax query failed (even though I'm using callback error functions). I couldn't reproduce it in IE8, so I'm going to assume this is because I'm using bleeding-edge Chrome 4 and not a reflection on Safari/WebKit. I don't have Firefox installed to test with...welp.
[/edit]

[KJake]

I was set to write a script to validate videos in my recordings directory against the database and delete them if they were orphaned until I realized that these extra files I'm seeing are actually TV recordings that recently disappeared from my Sage Recordings screen and I can see them in my Video Library now.

So I kept going and ended up with a script that got the seeker/video_storage property, called DirectoryListing() on the path, passed each file that ended in .avi, .mpg, .divx, or .ts to GetMediaFileForFilePath() and interrogated the object returned to see if IsLibraryFile was set to true.

Great, now I have a list of video files that should only be TVFiles, not part of the Library. All I think I have to do is call MoveTVFileOutOfLibrary() and I'll be set, right?

I try one just in the browser:

http://sageserver:8080/sagex/api?c=MoveTVFileOutOfLibrary&1=mediafile:1735366

and I get: <Result></Result>

I re-do the GetMediaFileForFilePath() and IsLibraryFile is still true.

What's going on? Any ideas? Does this have to be a POST instead of a GET?

Here's my code if following that is easier than my blabbering


I am limiting to the first 5 files in the directory since I have an alert in here right now and it wouldn't be fun to have to dismiss ~50 dialogs.

// query Sage.properies for the recordings path(s)
getRecordingPath = function () {
	$.jsonp({
		url: "/sagex/api",
		data: {
			"c": "GetProperty",
			"1": "seeker/video_storage",
			"2": "null",
		},
		callbackParameter: "jsoncallback",
		success: function(data, msg) {
			// send only the first path - I only have one
			listDir(data.Result.toString().split(",",1)[0]);
		},
		error: function(data, msg) {
			return false;
		}
	});
}

// use API to get directory listing
listDir = function (path) {
	$.jsonp({
		url: "/sagex/api",
		data: {
			"c": "DirectoryListing",
			"1": path,
			"size": "5",
		},
		callbackParameter: "jsoncallback",
		success: function(data, msg) {
			// iterate
			$.each(data.Result, function(i,item){
				// only consider video files with these extensions and send filename
				if (item.match(/\.ts$|\.divx$|\.mpg$|\.avi$/)) { checkDb(item); }								
			});
		},
		error: function(data, msg) {
			return false;
		}
	});
}

// find the MediaFile object in the database based on full file path
checkDb = function (file) {
	$.jsonp({
		url: "/sagex/api",
		data: {
			"c": "GetMediaFileForFilePath",
			"1": file,
		},
		callbackParameter: "jsoncallback",
		success: function(data, msg) {
			// only consider files that are Library files
			if (data.MediaFile.IsLibraryFile == true) {
				// print status message to browser
				$("body").append("Moving TVFile out of Library: " + file + "<br/>");
				// send MediaFileID for sage oject ref
				moveTVFileOutOfLibrary(data.MediaFile.MediaFileID);
			}
		},
		error: function(data, msg) {
			return false;
		}
	});
}

// finally, move that TV file out of the Library
moveTVFileOutOfLibrary = function (mediaFileID) {
	$.jsonp({
		url: "/sagex/api",
		data: {
			"c": "MoveTVFileOutOfLibrary",
			"1": "mediafile:" + mediaFileID,
		},
		callbackParameter: "jsoncallback",
		success: function(data, msg) {
			alert(msg);
			return true;
		},
		error: function(data, msg) {
			return false;
		}
	});
}

[stuckless]

I think your problem is basically a failure to fully understand those specific APIs. MoveTVOutOfLibrary() is only valid for a TV file, and since your files are in the Video Library section, then that API will not work on it. MoveTVOutOfLibrary() sets the "archive" flag for the recording and moves it to the "Archived" section in the Recordings menu.

Perhaps what you want to do is list all files that are in the Recording Import directory and get the mediafile, and then call IsTVFile() on the file. If that returns false, then you have a "Video" file in your Recordings dir, which is probably an orphaned file.

[KJake]

Originally Posted by stuckless

I think your problem is basically a failure to fully understand those specific APIs. MoveTVOutOfLibrary() is only valid for a TV file, and since your files are in the Video Library section, then that API will not work on it. MoveTVOutOfLibrary() sets the "archive" flag for the recording and moves it to the "Archived" section in the Recordings menu.

Perhaps what you want to do is list all files that are in the Recording Import directory and get the mediafile, and then call IsTVFile() on the file. If that returns false, then you have a "Video" file in your Recordings dir, which is probably an orphaned file.

OK, Yup, I follow you.

These all have IsTVFile = false, so the MoveTVFileOutOfLibrary() isn't going to work afterall. What is the best way to get them to be a TVFile again? From what I can tell, Sage still has all the metadata for each file (except all the EP style Show IDs have been changed to MF).

[stuckless]

Originally Posted by KJake

OK, Yup, I follow you.

These all have IsTVFile = false, so the MoveTVFileOutOfLibrary() isn't going to work afterall. What is the best way to get them to be a TVFile again? From what I can tell, Sage still has all the metadata for each file (except all the EP style Show IDs have been changed to MF).

If you have bmt 3.1 installed you can use the web UI. Use the "Browse" feature to browse the videos. Then for each video that you want to import into the Sage Recordings, you can click on the video, and then check the "Sage Recording" checkbox and save.

[bcjenkins]

Sean,

Is there a method for retrieving the thumbnail for the media object? I tried the following:

http://mediaserver:8080/sagex/api?command=GetThumbnail&1=3487896

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

I am more of a hack than anything else, so be nice

EDIT ** Found it: http://mediaserver:8080/sagex/media/thumbnail/3487896 - Cool

Thanks,

B

[stuckless]

you can also use poster, background, and banner, instead of the thumbnail, to retrieve fanart for the mediafile. ie, /sagex/media/poster/.

What is cool, if you are using the fanart, is that your can also apply a dynamic transform to the request....

Give this a try .
http://mediaserver:8080/sagex/media/...: reflection}]

[bcjenkins]

After reading through the api docs, I don't suppose there would be anything stopping anyone from really doing a nice integration with Boxee, XBMC, Plex, etc.

Pretty cool stuff. I am trying to shake some rust out of my AS3 coding and will be working on a widget which you can plug into your FB page, etc.

B

[KJake]

Originally Posted by stuckless

If you have bmt 3.1 installed you can use the web UI. Use the "Browse" feature to browse the videos. Then for each video that you want to import into the Sage Recordings, you can click on the video, and then check the "Sage Recording" checkbox and save.

I was hoping to automate it all - but I did as you said and used BMT to move them all back as a recording. One problem though, I recorded movies and they were given a EP style ID instead of a MV style, so the Movie grouping doesn't work in the STVs.

I tried manually setting the Show ID / EPGID using neilm's webserver and also making sure that BMT was set to Movie for each title, but neither worked. Any idea how to fix this?

[stuckless]

Originally Posted by KJake

I was hoping to automate it all - but I did as you said and used BMT to move them all back as a recording. One problem though, I recorded movies and they were given a EP style ID instead of a MV style, so the Movie grouping doesn't work in the STVs.

I tried manually setting the Show ID / EPGID using neilm's webserver and also making sure that BMT was set to Movie for each title, but neither worked. Any idea how to fix this?

I don't have any suggestions. I don't really know how sage can determine if a recording is a movie. If someone has any information then I'll try to update bmt accordingly.

[jaminben]

Originally Posted by stuckless

I don't have any suggestions. I don't really know how sage can determine if a recording is a movie. If someone has any information then I'll try to update bmt accordingly.

This is for SageMC....as far as I know it uses your guide data and a category to determine if a show is a movie or not. Within the options you can specify what category your guide uses to display movies then filters TV shows around this. I would assume that the default UI does something similar.

movieCat = GetProperty("sagemc/movie_category", "Movie")

[jaminben]

Originally Posted by KJake

I was hoping to automate it all - but I did as you said and used BMT to move them all back as a recording. One problem though, I recorded movies and they were given a EP style ID instead of a MV style, so the Movie grouping doesn't work in the STVs.

I tried manually setting the Show ID / EPGID using neilm's webserver and also making sure that BMT was set to Movie for each title, but neither worked. Any idea how to fix this?

Based on my above reply, you should be able to use the web UI and manually change the category to "Movie" and they will appear in the recorded section as movies. This is dependant on what you set your movies to use in the setup. Mine just happens to be "Movie" and thats what my guide data also uses for films.

Can't say I've ever tried this though

EDIT:

Ok, so I just tried this and it does indeed work......for SageMC anyway. I would assume that the same would be true for the default UI, but you know what assume done don't you

[Tiki]

Originally Posted by jaminben

This is for SageMC....as far as I know it uses your guide data and a category to determine if a show is a movie or not. Within the options you can specify what category your guide uses to display movies then filters TV shows around this. I would assume that the default UI does something similar.

movieCat = GetProperty("sagemc/movie_category", "Movie")

The Malore-style menus (which are part of the "hidden extras" in the standard Sage3 STV) also loook at the category. If it is "Movie" they get grouped together in the Recordings screen. Also, there is a setup for alternate movie category. The default value for this is "Film". Sage will also group items with this category name together.

I don't know if any of the STV's use the Episode ID for grouping, but from what I have noticed, there are at least 3 formats typcially used for the episode ID. If the airing is an episode in a series with a Unique episode number (like an episode of Siendeld for example) it begins with "EP" followed by a bunch of numbers. If it is a movie, it begins with "MV", if it is a TV show but there is no unique episode info, it gets a "SH" prefix.

I am not positive, but I think these episode IDs get assigned by the EPG provider (typically Zap2It in the US).

[KJake]

Yup, changing the category does help, I didn't notice that they had lost that. But Tiki is correct, they really need to have the MV part to be fully considered a movie. Thanks for all the help!

[stuckless]

Originally Posted by Tiki

TI don't know if any of the STV's use the Episode ID for grouping, but from what I have noticed, there are at least 3 formats typcially used for the episode ID. If the airing is an episode in a series with a Unique episode number (like an episode of Siendeld for example) it begins with "EP" followed by a bunch of numbers. If it is a movie, it begins with "MV", if it is a TV show but there is no unique episode info, it gets a "SH" prefix.

I am not positive, but I think these episode IDs get assigned by the EPG provider (typically Zap2It in the US).

Thanks... I'll make a note to update bmt with this logic when it's importing sage recordings.

[jaminben]

Originally Posted by Tiki

I don't know if any of the STV's use the Episode ID for grouping, but from what I have noticed, there are at least 3 formats typcially used for the episode ID. If the airing is an episode in a series with a Unique episode number (like an episode of Siendeld for example) it begins with "EP" followed by a bunch of numbers. If it is a movie, it begins with "MV", if it is a TV show but there is no unique episode info, it gets a "SH" prefix.

I am not positive, but I think these episode IDs get assigned by the EPG provider (typically Zap2It in the US).

Ah, I see that as well now.....there is also a fourth version which uses 'SP'. Not sure what the 'SP' one does though. I wonder where it gets this info from as I don't use Zap2It but an xml importer as I'm in the UK.

[Tiki]

Originally Posted by jaminben

Ah, I see that as well now.....there is also a fourth version which uses 'SP'. Not sure what the 'SP' one does though. I wonder where it gets this info from as I don't use Zap2It but an xml importer as I'm in the UK.

I did a search (because I remembered seeing a post about these ID codes somewhere before) and found this link in the FAQ sticky:
http://forums.sagetv.com/forums/show...2745#post32745

SP = sports

It appears that the episode id is supposed to be a globally unique identifier, so all Sage users should have the same ID for the same show and ideally no two shows should have the same ID (unless they are re-runs of the same show). The SageAPIs related to shows and airings have a parameter for ShowExternalID. External EPG plugins are supposed to supply this parameter for each show as well, but I don't know how this ID is generated. Will a particular episode of a TV show have the same ID if the guide data is supplied by Zap2It versus some XMLTV plugin?

In theory, if you wanted to you could create your own content (home movie) and assign it a unique ID, but I haven't seen any rules for creating the GUID.

PS - I just confirmed that the ID's shown in Sage match the Zap2It listings (at least if you use Zap2It as your EPG source as I do). If you click on a specific episode title in the Zap2It listings, the link will include the ID. For example, tonight's episode of "House" is http://tvlistings.zap2it.com/tv/hous...EP006883590117
When I look-up this episode in Sage, it shows the ID as EP6883590117.

Next week's episode has this link: http://tvlistings.zap2it.com/tv/hous...EP006883590118.

I know that some screens in Sage (i.e. the Malore Menus) display the last 4 digits of the Episode ID as the Episode number. These numbers are usually sequential with the original air date, but not always. In the examples above, this would be episodes 117 and 118.

Interestingly, if I just click on the link for House, I get http://tvlistings.zap2it.com/tv/house/EP00688359

So, it appears that somebody (Zap2It) assigns the unique ID of 688359 to the series "House", and "0117" is the episode number. Note this episode numbering is different from the Season# Episode# format commonly used when dealing with DVD's of TV shows. There is no season #. So for a show with 22 episodes per season, Episode 24 would be Season 2, Episode 2 (probably, unless the ID numbers are out of sequence, which they sometimes are).

[razrsharpe]

Sean,

We are having some issues that we have linked back to the sagex.api (we = ortus team... specifically me and jphipps).

Using sagex.api.Configuration.SetProperty and GetProperty. When these methods are called from an extender they always set/get the server properties (not the UI properties in MACAddress.properties). We tried every combination of using the UIContext, not using the UIContext, setting the UIContext globally, etc. Nothing we tried works. When we use greg's api everything works as expected. IIRC you had some issues figuring out what the context is automatically and wonder if that could have something to do with it?

Thanks for your continued work on this... we really like the sagex.api and would rather not go through the hassle of switching over to greg's but we don't want to use two api's that should accomplish the same thing either...

Any thoughts?

[stuckless]

Here's a short history....

When I originally wrote the sagex api, it was mainly for remote api purposes. And the UIContext stuff didn't really come into play. later when I needed the UI context, I tried the ThreadLocal approach, but as jphipps noted in another thread, threadlocal doesn work very well in the sagetv UI, which really where it counts So, I deprecated that approach, and then autogenerated methods that accepted a UIContext arg. I created a type for UIContext to get around an issue with method signatures.

So, on to your problem... ultimately, the 3 following calls should yield the same result.

sagex.api.Configuration.GetProperty(new UIContext("MACADDRESS"), "MyProp", null)
sagex.SageAPI.call("MACADDRESS", "GetProperty", new Object[] {"MyProp",null})
sage.SageTV.apiUI("MACADDRESS", "GetProperty", new Object[] {"MyProp",null})

BUT, the sagex api will ONLY ever use a context if a UIContext object is passed. Using SageAPI.setUIContext() is discouraged, since it doesn't work reliably. I don't actually do any work to "discover" the context. Either it is passed in, or it is not used.

It should also be noted as well, that GetUIContext() never resolves to the current UI Context when called from Java, which is unfortunate. So, the UI context must be passed from the STV into java in order for it to be a valid context.

I can't explain why, the UI context does not appear to work in your case. I will do some quick tests, to see if there is a problem. I did check the code, and basically the sagex api is a very thing facade to the real api... ie, args to just passed down to the real sage api, BUT, the uicontext is slightly different, in that I don't pass the UIContext object down to the sageapi, but rather ucontext.getName().

I'll let you know what I find.