[goofygrin]

this will probably be a pretty long post, but here's what i'm going to try to accomplish:

1) document what i think are the uses of a thin client/xml api
2) document what i would expect the api to look like that would support (1)

these will be my opinions, and i'm sure that there will be differences of opinions here.

for those of you who haven't, go take a look at http://www.sonos.com and look at that product.  i'd like to get to that level of integration (but obviously using pdas or laptops for the remote unless someone's got a better idea [nokia 770 tablet?]).  i want an xbox running xbmc to be able to be used as a 1) digital streamer for video and audio attached to a display device (likely to be controlled by a remote or a web ui); and 2) a headless (no display) streamer controlled by a web/thin/pda interface (to compete with sonos/slimbox).  i want to be able to run a server app on my server and have it control multiple xboxes to have a synchronized playback effect (or even, keep tabs of what my inlaws have watched in the guest bedroom).

a lot of people are buying into the xbox running xbmc (check out avsforum).  some of us are running 3, 4 or 10 xboxes in our houses.  can you imagine the possibility of zoneing your xboxes?  tracking what they play?  a lot of this stuff is science fiction right now, but that's the dream as i have it...  ramble off

what a thin client/xml api should support/what are the uses of a thin client/xml api
i would imagine that there are lots of things that people would like, but i'd recommend that we shoot for something like 90% coverage, so i'll define the features into three categories, must have, nice to have, code it yourself (aka. not gonna happen).

must have
- support audio files
- browse files
- view file info (either imdb/cd service or tag)
- manage playlist
 - view the playlist (including files by name/tag info)
 - add files to the playlist
 - reorder the playlist
 - clear the playlist
 - shuffle/random the playlist
- get info on the currently playing item (including thumbnail)
- player controls
 - play/pause toggle
 - stop
 - next track
 - previous track
 - fast forward
 - rewind

nice to have
- support videos (since you'll have the osd for video, the display on the "remote" app
- multiple playlists support
 - create/save
 - load
 - delete
- support pictures
- administration of the xbox (settings, resolutions, etc.)

write it yourself
- sending some random key combination to the ui
- rss (for crying out loud, who reads rss on their tv?  there's no resolution for that).
- share manipulation (this is what the xml is for)
- other crap that i wouldn't use :d

so how do we support all this?
operations to support all that crap up there
(note that this is off the cuff, so don't beat me up if some of it is whack)

incoming command message types
there are two types of incoming command message types:
- get
- post
(and you thought it would be something special!

get commands are done via the query string.  an example would be to simulate pressing play, why send a whole bunch of xml when you can say xbmcxml?command=play

on the back end, the code is a little ugly, but back end code is supposed to be ugly to make the front end easier (psuedocode):

class requesthandler
{
 public xml handlerequest( querystring querystring )
 {
   xml responsenode = new xml( "<response></response>" );
 
   string commandname = querystring["command"];
   icommand commandhandler = commandfactory.get( commandname );
   responsenode.appendchild(
        commandhandler.handlerequestcommand( querystring["parameters"] ) );
   }
   return responsenode;
 }
}
class icommand
{
 public xml handlerequestcommand( xmlnode node );
 public xml handlerequestcommand( string parameters );
 
}
class commandfactory
{
 public static icommand get( string commandname )
 {
   // look up in the command registry [xml] for the class/library that's the handler
   // instantiate it
   // return it
   // this model allows for custom commands to be created
   // and not have to be merged into the code
 }
}

post commands will take an xml in the body of the message.  these will be useful for batch type operations, or operations where there is large sets of data coming across the wire.  examples would be saving preferences, saving an entire playlist.
an example xml would be similar to that which is in the xml wiki, but (minus the <?xml ?> tag, would look something like this:

<request>
 <command name="saveplaylist" id="0">
   <data>
     <playlist name="my playlist">
       <playlisttracks>
         <track order="0" filename="1.mp3" />
         <track order="1" filename="2.mp3" />
       </playlisttracks>
     </playlist>
   </data>
 </command>
 <command name="selectplaylist" id="1">
   <data>
     <playlist name="my playlist" />
   </data>
 </command>
</request>

(or using cdatas in elements, depending on what is decided -- given that we're dealing with funny unicode in some places, it might be worth it to take the hit of cdata'ing the things like filenames/tag info)

the post message type would be a request, made of 1 or more commands that had data associated to them.  on the back end, the code becomes simpler (psuedocode [note the similarity to the code above]):

class requesthandler
{
 public xml handlerequest( xml requestnode )
 {
   xml responsenode = new xml( "<response></response>" );
   foreach(
      xmlnode command in requestnode.selectnodes( "/request/command" ) )
   {
       string commandname = command.attributes["name"];
       icommand commandhandler = commandfactory.get( commandname );
       responsenode.appendchild(
         commandhandler.handlerequestcommand( command ) );
   }
   return responsenode;
 }
}
class icommand
{
 public xml handlerequestcommand( xmlnode node );
 public xml handlerequestcommand( string parameters );
 
}
class commandfactory
{
 public static icommand get( string commandname )
 {
   // look up in the command registry [xml] for the class/library that's the handler
   // instantiate it
   // return it

   // this model allows for custom commands to be created
   // and not have to be merged into the xbmc code
 }
}

outgoing message types
all outgoing messages will have a similar structure:

<response>
 <command id="" status="" />
</response>

say for play, the response would be (assuming play started):

<response>
 <command id="0" status="ok" />
</response>

let's say for a request to get a playlist's contents, the response might be:

<response>
 <command id="0" status="ok">
   <data>
     <playlist name="my playlist">
       <playlisttracks>
         <track order="0">
           <filename>1.mp3</filename>
           <title>title</title>
           <artist>artist</artist>
           <albumarturl>albumart.jpg</albumarturl>
           ...
         </track>
         <track order="1">
           <filename>2.mp3</filename>
           <title>title</title>
           <artist>artist</artist>
           <albumarturl>albumart.jpg</albumarturl>
           ...
         </track>
       </playlisttracks>
     </playlist>
   </data>
 </command>
</response>

let's say a request fails:

<response>
 <command id="0" status="error" errorcode="12" message="out of disk space" />
</response>

let's say there are three operations:

<request>
 <command name="saveplaylist" id="0">
   <data>
     <playlist name="my playlist">
       <playlisttracks>
         <track order="0" filename="1.mp3" />
         <track order="1" filename="2.mp3" />
       </playlisttracks>
     </playlist>
   </data>
 </command>
 <command name="selectplaylist" id="1">
   <data>
     <playlist name="my playlist" />
   </data>
 </command>
 <command name="shuffleplaylist" id="2" />
 <command name="play" id="3" />
</request>

which (assuming everything went ok) would give you the response:

<response>
 <command id="0" status="ok" />
 <command id="1" status="ok" />
 <command id="2" status="ok" />
 <command id="3" status="ok" />
</response>

now, let's say that the same request as above is sent, but selectplaylist fails, then the response would be:

<response>
 <command id="0" status="ok" />
 <command id="1" status="error" errorcode="12" message="playlist does not exist" />
 <command id="2" status="skipped" />
 <command id="3" status="skipped" />
</response>

(there is now the question, if on a batch command, if one command fails, do the next commands get skipped?  i'd say yes or maybe, depending on how robust you want the system).

but goofygrin, all you've talked to me about is how the messages/commands are sent.
right... let's talk about operations and messages.

operations
for right now, to do basic functionality:
- getcurrentlyplaying (that's more efficient than the current one! and includes all tag info/thumbfilename)
- getplaylistcontents (that's got more detail)
- additemtoplaylist
- additemstoplaylist (might be overloaded of the one above)
- removeitemfromplaylist
- shuffleplaylist
- moveplaylistitem
- clearplaylist
- play/pause toggle
- stop
- next
- previous
- ff
- reverse
- getbookmarks (optionally get subdirectory data as well, but malformed bookmarks will kill this)
- getfilesindirectory (with tag info, optionally all subdirectories)
- getthumbnail (since the file is off somewhere, what i did was filecopy to the q:\web directory to a temp file )

each one of these operations should be supported by an operationhandler class that implements ihandler and will be very modular.

messages
- request
- response
- command
- file type=file (or just file)
- file type=folder (or just folder)
- currentlyplayingdata
- playlist
- playlisttrack (might be the same as file, or might include file since playlisttrack includes the position)
- bookmark

the actual definition of the content of these messages is fairly simple and probably will change over time as features are added.

so if you're still with me, bravo!  if you only read to the end, don't come to me asking questions later

[darkie]

just a quick read. seems we are both pretty much at the same line. although i tend to use elements faster then attributes.
batching multiple commands is also what i had in mind (not that clear in the current xml api)
i didn't work with the status code, i just picked another element name. 'error' instead of 'result'.

how the processing is done on the backend is still a bit unknown. tinyxml is in fact only good (read fast) when reading/writing directly from/to files. so i was using normal string operations myself (doesn't have to be that bad at all) when creating xml responses.
reading requests using an xml parser is ofcours a good thing.

what needs to be done is specifying all xml structures now. there should be not many of those. xbmc internally uses a lot of string commands and request to define its behaviour. using those would save a lot of new code (and thus bugs) and makes it easier to maintain. also, keeping all functionality at one place in xbmc is a good thing (but that is what xml api users will not care about)
that is what for example '<command type="buildin">' was for. the same is also used in python and xml gui files

[Livin]

guys,

i'm not a developer (have done some minor scripting & asp for my home automation projects) but i am a power user when it comes to home theater/home automation/whole house audio... so i'd like to give a little input.

i think that building an xbmc fully functional remote control interface (something that can be used on touchscreens) is perfect! i've used several wireless windowsce devices and various other things (like the 3com audrey) to control my home automation and voice recognition and they all have some issues... the only way to do this as universally as possible is to do it old-school html, which we all know sucks.

wince/pocketpc devices will not be jscript/ajax capable. you must install a jvm. not many options here; sun no longer supports personaljava and the others... who knows?
good info here..
http://www.berka.name/stan/jvm-ppc/java_for_pda.html


as for the whole home (aka multi-zone) audio... this would be amazing!

the options i see are:
a) server app on a pc on the lan
b) have a 'master' xbmc run the server app

... the server app would do zone management; track zone status, information, and sync zones when requested.

ideally we'd be able to connect a touchscreen to the xbox directly. then we could place an xbox in each zone (room) and control it locally while still having the option to control other zones of the home. but unless someone builds usb mouse support into xbmc we will not have this.

i built a python script to send commands to my homeseer home automation server, so adding multi-zone audio would be the icing on the cake!

if you can pull this off... i love you guys!!!

i'll be the first to offer a riggerous testing environment! i'll get a few xboxs just to test it!

[goofygrin]

affini,

javascript doesn't require a jvm. there's no way i'm writing java code ever again. true java is a waste of time (so all you kids in school, learn something that will get you paid (i'd recommend c#.net, c++ is dead too unless you want to write compilers or games [or xbmc :d]).

however, i think that you are probably right when you say that pda browsers won't support some of the higher tech javascripts.... pdas might still have to be supported with a native application... but the native application will be fed from the new xml back end interface, so it's all good.

as far as touch screen, there are two options: use the web interface with something like the nokia or write a thick client that's got better touch support (like big buttons and text and stuff). either way, you'll be better off with the better back end services.

now, you can get, for $40 on ebay, a 5" lcd that sits on top of the xbox and just use a remote...

[goofygrin]

seems we are both pretty much at the same line. although i tend to use elements faster then attributes.

you'll get over than when you have more than 15 lines of xml going over the wire.  i was sending somewhere in the neighborhood of 3+ megs of xml over the wire, and just by switching to attributes, the xml went from an average of 3 megs to 600k... so it makes a huge difference in bandwith.

batching multiple commands is also what i had in mind (not that clear in the current xml api)

i think that command batches won't be all that useful personally.  it's not like we're trying to limit the amount of data across the wire... but you had mentioned it, so i threw it out there, because there will be times where you'll need to run more than one command at a time (like i get the current playlist, get the currently playing file index [in the playlist] and get all the files in the current playlist, which requires three hits).

i didn't work with the status code, i just picked another element name. 'error' instead of 'result'.

the reason i did this is because in my js side i can do the following:
(edit: i reread what you said, and i think we are agreeing, just calling the element/attribute something else -- all the attribute/element names i gave were just examples and might not be the right thing)

var val = commandnode.attributes["result"];
if ( val == "ok" )
{
 // do the good stuff
}
else
{
 // handle the error.
}

this makes it easier to process to not have to look in multiple places.

how the processing is done on the backend is still a bit unknown.

i get the feeling this will be the biggest problem, unless we can get some mainstream help.  my c++ is weak at best...  i won't bother with python or ruby or any of those fringe languages because frankly, noone will pay me to know them.

tinyxml is in fact only good (read fast) when reading/writing directly from/to files. so i was using normal string operations myself (doesn't have to be that bad at all) when creating xml responses.

not sure what tinyxml is, but we're going to need some sort of dom/xmlparser on the backend to at the very least, read the requests...  if we have to make the responses by hand, that's way less painful than reading the requests as strings...

strings are foolish (we've had this discussion already in this thread).

reading requests using an xml parser is ofcours a good thing.

agreed.

what needs to be done is specifying all xml structures now. there should be not many of those.

it will probably take someone about 2 hours at most to define all the structures...

xbmc internally uses a lot of string commands and request to define its behaviour. using those would save a lot of new code (and thus bugs) and makes it easier to maintain.

well that depends... if the code is crap, then we're putting more strain on the crap.  if the code is good, then we're fine.  i don't know how good or bad the code is, so i can't help.  if the code was more oo, then this would be way easier, but from what i've seen, it's more procedural than anything...

also, keeping all functionality at one place in xbmc is a good thing (but that is what xml api users will not care about)
that is what for example '<command type="buildin">' was for. the same is also used in python and xml gui files

again, it all depends on the quality of the code in the first place...

i'm somewhat worried with the quality of the main xbmc code because of the issues we've already seen with getcurrentlyplaying causing the system to start to get really slow.  honestly, a call to get something out of memory should cause 0 overhead (maybe 1% in order to wrap it up into xml).  however this could be one instance of the http interface doing something wrong and everything else is a-ok (although i wish this were so... why if i hit stop, then play does the play command go into the ether?  if i hit stop, then wait 5 seconds, then play it works?  stop should just be like... stop and not whack the system...)

leep:

[darkie]

don't wory abouy the backend, i will handle all that. i think i have enough c++ experience for that. btw, tinyxml is a xml dom parser.

i'm somewhat worried with the quality of the main xbmc code because of the issues we've already seen with getcurrentlyplaying causing the system to start to get really slow.

getcurrentlyplaying is a httpapi command. that is also one of the reasons why to start a new api interface. also keep in mind that retrieving large data structures (directoty listings for example) will slow xbmc a bit down. there is simply to much data that has to be formatted . but even that is controllable on the back end.
the main xbmc code i was talking about is good enough to be used (and can be changed anyway if needed).

it will probably take someone about 2 hours at most to define all the structures...

true, to comeup however with interfaces that everybody likes wil cost a few more hours.

[pike]

not all possible applications can run js and thus parse the xml output, so i wonder if a "legacy outputmode" will be feasible ?

there has been worries from one certain person who spent alot of time writing a mirc script to remote control xbmc. he's too shy to pop the question himself though

[jiz_king]

the ps2's browser has good js support i think. and with wifi built in it'd be a great remote.

[goofygrin]

not all possible applications can run js and thus parse the xml output, so i wonder if a "legacy outputmode" will be feasible ?

there has been worries from one certain person who spent alot of time writing a mirc script to remote control xbmc. he's too shy to pop the question himself though

an interface that someone wrote... that only they use?

who they heck uses mirc to control an xbox? that's the definition of "fringe user." most people don't even know what mirc is!

i'd say to not remove the old interfaces, just create a new one and let these "fringe" players migrate as needed.

[drakethegreat]

the ps2's browser has good js support i think. and with wifi built in it'd be a great remote.

did you mean the psp?

[pike]

no goofygrin, it's still in development, thus not released yet. i tested it and it works fine, it's an amip style of script

and that type of bashing i dont appreciate

and who uses mirc ? i do, we have an irc channel with more than 150 people (although spamming amip stuff there is prohibited)

[goofygrin]

no goofygrin, it's still in development, thus not released yet. i tested it and it works fine, it's an amip style of script

and that type of bashing i dont appreciate

and who uses mirc ? i do, we have an irc channel with more than 150 people (although spamming amip stuff there is prohibited)

bashing or not, it's a fringe type app, as is irc.

ask 100 people on the street if they've ever heard of irc and you *might* get 3-4 that have.

ask people what they'd want for xbmc, and i bet that the ability to control it via an irc client would rank really low on the wish list (if it even registers at all).

leave the support for it, but i wouldn't make any special concessions for it...

this thread is for a web interface... it's morphed into an xml service type interface discussion, and that's fine since that supports the web interface. maybe there needs to be a separate discussion for the xml interface and threads for the consumers of that interface so you won't have to read my honest opinion (aka bashing) of fringe (and irc and muds and the like *definitely* count as out of the norm, fringe type activities) activities.

[goofygrin]

so that you can maybe swallow my assiness in stride a little better about supporting what i consider to be fringe things, let me tell you why i feel this way:

(short version: if you try and be the end all be all for everything, you'll never get anything done and you'll never be anything for anything).

(long version below)

let's say you're a packrat and your garage has more crap in it than you can imagine.  you've got bits and pieces all over the place of projects, parts, tools, toys, boxes of clothes to donate, tile, trash, and whatever else you might find (no cars though, that's not the american way!.

you finally get sick of it and decide to clean it up and get some use out of your garage again.

you start cleaning one weekend and you barely make a dent.  you get disgusted and the garage stays a hell hole until it spontaneously combusts and your whole house burns down.

ok, so how do you avoid your house burning down?  you need to clean out the garage, but attacking the entire problem at once isn't going to happen.  you have to attack small sections with a goal in mind.

so, you have an overall goal of cleaning the garage (e.g. supporting other, remote interfaces for xbmc), and instead of attacking everything at once (e.g. worrying about this interface and that interface and that method and this method, trying to be all to everything all at once), you decide to work in iterations, sectioning off small sections that will lead you to the final goal (e.g. figuring out some small set of functionality and implementing it, then choosing another small set and doing it).

so, sure you want your fringe apps/commands/methods supported... great... if you try and throw those in here now as "don't break my stuff with what you're doing", then you kill any momentum.  if it gets added to the end goal/feature set, then great, it'll get done when that partition is made/coded/when you do it :d.

edit: and if that developer isn't willing to speak up, then maybe they're fine with any changes we make? what's that saying? "the meek shall inherit the earth, if that's ok with the rest of you guys?" :d

[pike]

yes, this thread/discussion is about 2 things:

1. a beefed up api
2. a beefed up "skin" for webremote

what i was talking about is the old api, which a guy has used for a project that has taken several months so far. i don't think we should just say 'to hell with you' for his work, do you ?

maybe you do, but you don't have to voice your opinions this loudly here in our forum. let's keep it civilised ok ?

so all i wonder is if either
a) will old api stay
or
b) will new api have a 'legacy mode' for returned answers.

we are all free to discuss it, but it's ultimately upto team xbmc.
now who am i ? i'm a major part of this project although i don't code. so take a chill pill there.

ps - english is my 2nd language so i may have missed some nyances of your rant

[goofygrin]

yes, this thread/discussion is about 2 things:

1. a beefed up api
2. a beefed up "skin" for webremote

if you think a new web interface is just a skin, then you've got the wrong idea. it's a web app. if it was just a skin, then we'd just make a css and have been done a long time ago.

what i was talking about is the old api, which a guy has used for a project that has taken several months so far. i don't think we should just say 'to hell with you' for his work, do you ?

nope... i never said to remove the old api... in fact, if we find that the old api is doing something in an unefficient way, then we should probably fix it at the same time.

maybe you do, but you don't have to voice your opinions this loudly here in our forum. let's keep it civilised ok ?

your house, you tell me to leave and i'll change my hosts file and never come back, but i am being civilized.

so all i wonder is if either
a) will old api stay
or
b) will new api have a 'legacy mode' for returned answers.

no legacy mode, that's what makes windows such a pita and makes it hard for microsoft to really innovate because they have to support all these legacy type applications. leave the old interface out there, but i'd say that little effort should be put into it if the xml interface will become the "standard."

we are all free to discuss it, but it's ultimately upto team xbmc.
now who am i ? i'm a major part of this project although i don't code. so take a chill pill there.

i can read that you're a pm, which means that your job is to filter all the crap coming up and down the chain. so you have to deal with cranky developers (who don't get paid for this crap) and with cranky users who's stuff doesn't do what they want it to do.

as far as approval from the xbmc team... well that's great... do we have to do a proposal with volumes of documentation for them? this is an open source thing, so we could just go off on our own and do something... it might never get into the main code stream... but less beaurocracy that way.

ps - english is my 2nd language so i may have missed some nyances of your rant

(nuances) i speak a couple languages, so i can understand the pain... just understand that i strive for similar goals, but i probably get there in a different way than most developers (and i am very successful).