Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Media Renderer Changes for 4.4
This first post is for driver developers. For the changes that affect users, see the next post.

So, just to provide a short hand for third party media renderer driver writers, so that they can get upgraded, here's what has changed. The changes aren't very significant.


Standard Base Class - There are two strategies you can take to get updated. The first is to base your driver on the new standard renderer base class. This will vastly reduce the effort required and make it very unlikely you'll be affected by any future changes to how media renderers work as well. So it's the winning strategy all around if you can do it. It does though require that you be strictly compliant and you have to totally work the standard way.

If you are going to go this route, just copy the device simulator audio driver, copy it into your driver, and then just plug in the code specific to your driver where appropriate. Almost all the code will just be your device specific code.

Do It Yourself - The other strategy is to do it yourself. This gives you more flexibility but you have to implement everything yourself. And you'll be affected in the future if any more changes as required. If you already have an existing driver, then you will just make a fairly small number of changes to what you already have. I'll list those below.

If you go this route, with an existing driver, then the initially just get it working in the V1 sort of way. That will require just a few changes and will get you back going quickly. You can then think about supporting the new V2 architecture, which isn't very difficult either, though supporting both V1 and V2 in the same driver is a little more annoying.

Changes Required

If you are going to change an existing driver and not base it on the new base class, you will need to make the following changes:
  • Change the memory buffer query backdoor query. See the base class for the code. It's very similar to what you already have. The big change is mostly a removal of some of the options there. Clients no longer come to the renderer driver for cover art. Now you only return playlist info. But it's all black box stuff just as it was before.
  • You don't treat PlayMedia with an Item cookie as a special case anymore. So this is also just removing some special case code. Look at the base class for an example, but most likely it'll just be a case of deleting the block where you check if it's an item cookie and not enqueing.
  • There is a new DelPlaylistItem field, which is used to delete playlist items, which is a card field and takes the unique item id for the item to delete. And also, given the previous point above, there is a SelPlaylistItem field to select a current item, which also takes a unique id.
  • There are some simple changes in the commands on the playlist manager, to support the fact that repos can be queued up with the playlist items. Look at the base class for examples. They are very simple changes.
  • When a new playlist item comes up, don't use the default repo to get metadata, use the repo queued up in the repo item.
  • You don't need to flush the playlist if a new default repo is set, since the repos are queued in the individual items.
  • There is a new PLItemKey field (or MREND#PLItemKey in V2 mode), whose content is in the form 'repo cookie'. This should be updated any time the playlist item changes, and cleared when the list is empty. This is used by widgets like the Media Image widget, to get the info they need to go grab the cover art and update. If there is an item cookie, use that. If not, use the collection cookie.

To my knowledge, that's all you need to do. It won't take long. Don't bother until the next drop (.920), when all the changes are complete.

Optional Bits

Things you probably want to do but don't absolutely have to, though it'll probably mean your driver won't work with the auto-generation system or room config based Android/iOS apps.
  • You should support the new MediaState field, which is a standard means of reporting the current playback state. You could do it in addition to any existing state field you already have, though the shipped drivers have all migrated to this and removed any driver specific ones. You don't have to do this field, but it won't totally work with auto-generation if you don't. Look at the base class for the state enumeration and the set up of the field definition.
  • Similar to above, it would be good to support the new standard transport field. If you were already using the field name Transport, then you'll have to either not support it or update it to use the new standard transport commands. If you do, then it'll work with auto-generation. Again, see the base class for the field definition and enum. If you don't support all of the standard transport commands, just ignore the ones you can't do.
  • There is a helper method on the playlist manager class to get all of the field defs of all of the standard fields, in either V1 or V2 architecture mode. As long as you are ok with all of the fields in their standard forms, you can use that to load up your non-driver specific fields, to save a lot of grunt work. If you need any variations on any of the fields you'll still need to do them yourself, though you can at least just steal that code and only make changes as required to save work. All but a couple of them, in V1 mode, are the same as they were before.
  • All the standard renderers support random play from category mode now. If you can't support that, just ignore attempts to set that playlist mode. Just reject the field write.
  • An 'adjust volume' field is now standard, but if you can't do that, just do nothing.
Dean Roddey
Explorans limites defectum
As a user of CQC, there are some changes in media renderers you will need to deal with once you move to 4.3.920 and beyond. The big change is that we have begun the process (which may take some time to fully complete), of standardizing drivers. This will have huge benefits down the road, but it's just begun so far. We started with media renderers since they were already the most standardized, which paradoxically made them the most difficult to tackle in some ways.

The fully standard drivers are now called V2 drivers, and drivers that aren't standardized yet are V1. Any existing drivers will be available in both V1 and V2 versions, for backwards compatibility. You don't have to use the V2 ones, however things like the auto-generation system will only work with V2 drivers (of a given type once that type of driver has been standardized, which so far is only media renderers.)

Sticking with V1 Renderers

If you stick with the V1 renderers, you just have to deal with a small set of changes, that happened during the upgrade, though even there you will benefit in the long run since these introduce more standardization as well. The changes are:
  • Writing to PlayMedia with an item cookie no longer selects that item in the playlist. It acts like PlayMedia with any other type of cookie. It flushes the playlist and loads this one new item. This means that PlayMedia and EnqueueMedia fields are now fully symmetrical and there are no special case issues.
  • Selecting and deleting items in the playlist are done via SelPlaylistItem and DelPlaylistItem. These take a unique list item id (which is now available as one of the runtime values when you make a selection in the playlist.) You pass those in now instead of cookies.
  • The reason for the above is that renderers can now queue up stuff from multiple repos, so there may be two items in the list with the same cookie, but they aren't the same item. When you write to PlayMedia or EnqueueMedia now, you can do what you have always done, which is to pass a cookie. Or you can pass a cookie, a space, and a repository that that cookie belongs to. This allows you to queue up stuff from any repo arbitrarily. If you don't pass the repo, then the default one set on the driver is used, as it has been in the past.
  • There are now standard values for Transport fields, so you have to make slight adjustments if the renderer drivers you are using used different values. The only likely differences are Prev vs. Previous typically. Play, Stop, and Pause are basically always used. If a driver provided other options, those will have to be moved out into a different (driver proprietary) field by the driver writer, so you'll have to use that new field for the non-standard stuff.
  • There is now a standard MediaState field that indicates playing, paused, stopped, ect... which can be used to drive interface widgets that indicate media playback mode. These were previous not at all standardized and it made things quite difficult when trying to create reusable templates.
  • Media Image widgets now are associated with a PLItemKey field, instead of one of the current playlist item cookie fields. The reason being that the widget needs both the current items repo and cookie info together. They will be updated automatically, but if you are doing any 'associate with field' commands on media image widgets, you will have to update them to use this new field.

That should be it. For most folks, the changes won't take more than ten or fifteen minutes to fix most likely.

Upgrade to V2 Renderers

If you choose this route, the above stuff still applies, however you'll have to change the field names for all of the standard fields. The standardization involves the use of 'device classes', which define standard field interfaces for this or that chunk of functionality that any driver might implement. To avoid field name classes if drivers implement more than one such chunk, the field names now have a device class prefix on them.

V2 Media Renderers now implement three device classes:
  • Audio - This class provides volume and mute control. They will be prefixed by AUD#, so Volume becomes AUD#Volume, mute becomes AUD#Mute.
  • Media Transport - This class provides transport control and the indicator of current media state. So Transport becomes MTRANS#Transport and the new media state field discussed above is MTRANS#MediaState.
  • Media Renderer - This covers all of the standard fields of media renderers. These will now be prefixed by MREND#, so MREND#CurItemName, MREND#PLItemCnt, and so forth.

Since the names of the fields are what they were before but with a prefix, search and replace will be your friend and should make it fairly easy to handle these name changes.

Driver Selection Dialog

The driver selection dialog has been expanded to display device class info when you select a V2 driver, though there aren't many of them yet. The description should indicate it's a V2 driver, and the presence of any device classes in the list would be another clue.

Later it will also be updated to allow filtering on device class in addition to the other filtering criteria currently provided.

Auto-Generation of Templates

The auto-generation stuff now only works with V2 drivers (where they have been defined and implemented, which is only for media renderers so far.) So, if you are using the auto-generation system, as of 4.3.920 or beyond you'll have to move over to the V2 versions of the media renderer drivers you are using after upgrading, and re-generate your templates. Since you are using auto-generated stuff, you won't be affected otherwise, since all of the changes are accounted for in the auto-generated output.
Dean Roddey
Explorans limites defectum
[This is no longer valid, so I removed it.]
Dean Roddey
Explorans limites defectum

Possibly Related Threads...
Thread Author Replies Views Last Post
  Media Art Issues - 4.5.1 daddyd 64 20,565 07-21-2014, 02:12 PM
Last Post: daddyd
  Media Repo Item Browser error pinballmark 10 6,216 09-03-2013, 05:00 PM
Last Post: pinballmark
  910 CQSL Media Repository issues rbroders 30 10,610 03-01-2013, 01:03 PM
Last Post: rbroders
  Feature Request - Unified Media Browser indygreg 5 3,269 01-06-2009, 04:00 AM
Last Post: jrlewis
  My media playlist browser broke! froop 67 18,066 12-27-2008, 11:38 PM
Last Post: Dean Roddey
  Media Repo License... SomeWhatLost 2 2,091 05-13-2007, 02:34 PM
Last Post: SomeWhatLost
  Problem with Media repo over 2 machines rm1759 7 3,254 01-22-2007, 07:41 PM
Last Post: Dean Roddey
  Media respository problem after 2.0.6 upgrade bryanb 34 13,737 01-16-2007, 12:19 PM
Last Post: Dean Roddey
  Media Repo Item Browser MikeW 1 2,325 01-14-2007, 08:30 PM
Last Post: Dean Roddey

Forum Jump:

Users browsing this thread: 1 Guest(s)