Dolby IMS2000, NEC NP-90MS02 API.

[Andrew Dumin]

Hi guys.
Tell me where me can get the API documentation for this device?

[Marcel Birgelen]

Not a single IMS and/or DCI server vendor has opened up their APIs to the public. I guess you need to contact Dolby and NEC for this and sign a special agreement to get access to those APIs.

[Steve Guttag]

It depends on what level of API you are going for. The NP-9MS02 is the Dolby IMS2000 and its API can be can be had but it all depends on how you want to control things. The Doremi API is not typical ASCII type commands. They are nasty HEX commands with a lot of repetition. I don't know if Dolby/Doremi still requires an NDA to receive them or not but talking with Dolby is your best bet. Now, doing ASCII type commands via Triggers/Macros is documented and available at the Doremi FTP site, if you have access to that.

[Carsten Kurz]

There's a short snippet on how to use the API interface (KLV communication protocol) on the legacy Doremi partner site. It does not contain any in-depth API documentation, though. There's also a FieldBulletin how to use RAW TCP between devices. As Steve says, depends on what you want to do.

[Marcel Birgelen]

Those advanced APIs like those being used by TMS software, are all under NDA and usually reserved for partners with agreed-upon contracts. From what I know from back in the Doremi days is that Doremi wants to get paid for this kind of access, together with some other strong commitments.

While over the years, some of those APIs have been (partially) leaked, they're obviously not supported by any of the suppliers.

[Steve Guttag]

I just checked on my copy of the KLV (V2.9) and it does have Confidential on it so I can't go into too much detail other than you can probably get a copy if you ask Dolby (what can it hurt to ask?). The real pain is in using it!!!! It's all HEX commands and the word length can be HUGE. The shortest word length is something like 25 or so bytes.

The "Raw TCP" document Carsten refers to is to fire a "Trigger." If you've ever gone into the Macro creation section of the server, you will have noted that there is a Trigger section too. JNIOR and eCNA automations are "blessed" in that both have dedicated "Signal" configurations that both systems know how to use. So for those two, you merely have to define the output that those automations are going to use...e.g. "SENDF1" is an eCNA type command. A simple trigger can be set up to look for that command from an eCNA. However, if you are going to have a command come from some "other" device, then you will need to set up a Trigger that is looking for "Any" and you must have the command follow the protocol in the Raw TCP document. it is just slightly cumbersome but you can use all ASCII type characters and just need to count the total characters since it has to know the word length (first part of the command). But hey...at least you can use standard TCP or UDP type commands.

But wait, you aren't done yet! A trigger does NOTHING until you link it to something (e.g. a macro). So, whatever you want the trigger to do (e.g. press "Play") there has to be a corresponding Macro that does that. That is easy enough to set up in the Macro Editor...but you aren't done yet. You still have to link the Trigger to the Macro. This can be done on a show-by-show basis (SPL) by putting the definition in by putting the trigger in the show (I've never done it myself) or, more commonly, by adding/modifying the "default_cues.xml" file located in the doremi/etc directory (and you will need root privileges to do that. But wait...the default_cues.xml file is only active IF A SHOW IS PLAYING!!!! Firing triggers via the default_cues.xml during an intermission does nothing. For completely random/asynchronous cues, you'll need to create a different file called firealarm_cues.xml (same directory). Those work regardless of if a show is running or not.

The Raw Ethernet document mentions none of this and, in fact, I don't know if it is documented anywhere and there is definitely not a step-by-step on it except what you might get from tech support. To help in the default_cues.xml or firealarm_cues.xml. the "easy" method (which I never used) was to make a dummy SPL that had all of the trigger and macro links in it. Save it...then find that SPL (via its UUID) and then rename it to the desired file and put it in the right directory. I believe, the latest IMS3000 software will do this for you (create a firealarm_cues.xml file from the Show Editor screen. Again, I have not tried it as I ended up making my own xml files and merely load them in on all new installations so they have whatever I've found I needed in the past.

Is it cumbersome? Yes, yes it is! Does it work? Seems to. I will say that the people at Dolby/Doremi were quite patient with me as I was learning it...all the while thinking "couldn't this be a LOT more simple?" There is also a certain sense of "accomplishment" when you fire your first successful KLV command. Oh...and I hope you like WSDL (SOAP web based APIs)...because that is where they (and seemingly many) are going. In fact, on the IMS3000, you can download the WSDL files right from the IMS3000's UI so you always have the current files for the version you are running. I'm not there yet!

[Marcel Birgelen]

Why Doremi went for KLV remains a misery to me, it's not like there weren't any other alternatives around when they built their first DCI hardware. But, it's probably because there is an SMPTE standard for it...

Yeah. the IMS3000 features a SOAP API, GDC also has one... Which is funny, since the whole world is moving towards REST APIs...

Then again, I mostly liked the idea behind SOAP, if it wasn't for the often very bloated implementations and slowness of lots of those SOAP based APIs...

[Steve Guttag]

There is a lot about Doremi that makes my scratch my head. As you can see, for the most part, I've just adapted as best I can. Where it sucks is when trying to integrate with other devices. Personally, I think there should be a robust ASCII command set that comes along for typical A/V integration because that just works and has the widest range of compatibility. If you want to have WSDL or other type APIs for the TMSes out there...fine but make sure the basics are covered by ASCII.

[Andrew Dumin]

We plan to create a program that will run the playlist if tickets are sold.

[Marcel Birgelen]

Is it always the same program you're running per screen or do intent to assign content dynamically to different screens?

[Steve Guttag]

I can tell you with Doremi...there is no simple "Play" command that just plays the content (I've requested it). It will play if content is loaded into the player (e.g. already selected and loaded and is paused). So you either have to trick it by having all shows start via the scheduler and then self pause, waiting for your play command (this is commonly done) or you will need to be more sophisticated and actually issue a play command that lists the SPL you want to play...that is what I do for automatic LSS200 tests (QC). The LSS200 test has an SPL with a known UUID that I created so an automation (eCNA) on a rigid timer fires up the theatre at a set time and then loads/runs the LSS200 show and then puts the theatre to bed.

For what you are doing, you may find it easier to let shows run on the schedule and just worry about turning the lamp on or not based on ticket sales. What do you care if the show runs without anyone in there so long as the the lamp is off to save on life and electricity?

[Marcel Birgelen]

Yeah, that's why I was asking if the shows are already pre-scheduled for a particular theater, which probably is the case. In that case you could load them but wait for an external play command or stop them once they're started.

Switching off the lamp could be rather easily done and you could maybe even issue a fade to zero command to the audio processor so, there is no audio playing too. Same for dimming the house lights, which could be done by firing the necessary cues to the automation controller or via a server trigger if stuff is connected serially or via GPIO.

[Steve Guttag]

See...the way I see it...always run the show...just don't turn the lamp on...if a late ticket sale occurs, turn the lamp on then to a show in progress (keeps the schedule for the day). The lights will dim down normally so money saved there and who cares if the sound is playing or not? Are you worried about the small incremental cost difference of an amplifier playing something versus nothing? For our VPF theatres, we always had a "lamp off" switch whereby if a no tickets were sold, it would still run the show but without the lamp...otherwise you would have to fill out a form stating why a show was missed. The TMS logged the show as a completed show...the TMS doesn't log if the lamp was on. If a customer came late, it was still just one switch away from turning the lamp on (or done via the TMS itself). Automations, including the eCNA, can now automate this, via software to monitor the POS' ticket sales (Eprad has their "nanohost").

[Marcel Birgelen]

It's just a single command to turn the fader to zero. I agree that it won't save all that much in energy, but it will still save a bit. It will also save a bit on the wear and tear of the equipment. In the end, cost savings are a cumulative of the many small things you can optimize.

You could go so far as just turn the lights and music on in the auditorium once the first ticket has been sold. If you're facing many empty shows, which is probably nothing new for any multiplex operating in the current environment, even those things can shave something off of your operational budget.