The following document was previously provided to OEM/SP customers integrating OtsAV within external systems and is published here for informational purposes without any assurances.
(Please be aware that some of the software release versions cited may not have been public releases, however, as much of the functionality discussed has now been integrated into OtsAV 1.94.128, this information will prove helpful to some.)
Media ID Preparation Kit OtsAV TV 1.94.029 (and subsequent updates) Ots Studio 1.03.014 otsmid 1.0 Ots Studio 1.03.014 This version of Ots Studio adds 12 new chunk types: - Item IDs - Artist IDs - Album IDs - From: Album IDs - Item Extensions - Album Extensions - From: Album Extensions - Item Comment - Album Comment - From: Album Comment - Object Item Notes - Object Notes The only one that matters for this discussion is the first one on the list - Item IDs. The others will not be mentioned any further. The Item IDs chunk is a multi-line text-based chunk that allows IDs to be defined for each item. From an OtsAV perspective, the only line that matters is the FIRST line. The format is a short user prefix for your company or firm, followed by a colon and then a 32-bit unique number which represents the actual ID. Eg: bcms:1234 The reason for the user prefix is to reduce the chances of clashing if you happen to have Ots files from other sources that are using IDs. You can also enter third-party IDs into the chunk, eg. Spotify IDs, though this has no effect in OtsAV. We won't discuss this any further. What is a mID? When we talk about "Media IDs" or "mIDs" we're talking about the 32-bit number that is stored in the first line of the Media IDs chunk. OtsAV 1.94.029 will read these IDs and store them in the Media Library (like with other changes, you need to use the "Easy Scan with Forced Refresh..." function to force all of the IDs to be read after you've added them to your Ots files). The IDs are freely defined by you. As they are stored in the Ots files, they become a permanent handle that you can use to uniquely identify each item without fear of them changing - unless you choose to change them. Presumably you are already running some kind of external database. So a good ID scheme may be simply to use the primary index key ID from your database table, assuming it's 32 bit. If this is not feasible, you can of course create a new mID field in your item database table and populate it sequentially, randomly or however you wish. How each customer chooses to do this is beyond the scope of this discussion, though here's a few important points about mIDs: - 0 is reserved. It means "unset", not defined, no ID. - As the IDs are 32-bit, this means you can use any number between 1 and over 4 billion (4294967295 to be precise!) - IDs may be entered as decimal, eg. 255, or as the hexadecimal equivalent by using a preceding 'x' or '0x', eg. xFF. Leading 0s don't cause harm. Case also doesn't matter. Therefore, all of the following are logically equivalent: 31438, x7ACE, 0x7AcE, 000031438, x000000000000000000007ace. - The preferred form, and the one that Ots uses internally when a string form must be created, and is also the most efficient to parse, is hexadecimal with a preceding 'x' and upper-case hex alphas. These are either in short form, eg. x9F, or padded to 8 significant digits (which is all that is ever required to represent 32-bits), eg. x0000009F. - In most places where mIDs are displayed in OtsAV, both the hexadeciaml and decimal representation is displayed to make it easier for the user if you're manually copying or entering the ID somewhere else and prefer one form over the other. - It is VERY important that the IDs you assign to each item are truly unique. If you use the same ID more than once, and multiple items with the same ID are imported into OtsAV, then any function that searches based on ID will have ambiguous results, which defeats the purpose of a unique and reliable ID. - Our philosophy on ID uniqueness is as follows: If the item is different, even just a little, eg. a minor edit tweak of some song (let's say the intro is slightly trimmed compared to your "base" version), then it should get a different ID. You should never have more than 1 item in your database with a given ID - unless the items are identical in every respect other than encoding characteristics - see next point. - The one area where using the same IDs makes total sense, is where you have another set of Ots files which are identical in all respects to the first set, except they are encoded differently. A common example would be an HD set vs an SD set - that kind of thing. If the two sets are really the same base media, same songs, some exact lengths, from the same source, completely identical other than one is encoded at a lower resolution and/or using a different codec - then, and only then, it indeed does make sense to use the same IDs. You would normally only load one set (eg. the HD set) onto a given client PC anyway, so there won't be any ambiguity when it comes to resolving the IDs later. It would be wasteful (and confusing) to use new IDs for a "mere" encoding variation. - Later we'll be extending this formally, and allow the specification of encoding variations (EVs) within the ID chunk as well. With this system you'll be able to define different profiles. But really, it doesn't matter. The main thing that is essential is a unique ID and sticking to the above rules. You already can easily separate different encodings by simply placing that folder tree - or some other - on a given system. - Just to re-iterate the above - since it's SO VITALLY IMPORTANT - in a slightly different way. Let's say you happen to have in your library 3 different versions of Michael Jackson's Billie Jean. Perhaps one came from the Thriller album CD, another from a compilation or greatest hits CD, and another is a video version from a DVD release. These would all obtain separate IDs. Even though the song is the same (and maybe in the case of the two audio-only versions, they even sound basically identical), they are actually from different sources and will be slightly different lengths, cuts, even minor speed variations, etc. If you use the same ID for all of them naively thinking that the "song is the same" then you're going to be in for a whole world of hurt later. Please don't do this! OK, so now you understand that you need to have a unique ID for each logically different item in your main media collection. How do you actually get the IDs into the Ots files? For a start, you should play with the new Ots Studio and experiment with the Item IDs chunk. You can add, inspect, change an ID very simply using the normal Ots Studio interface - just as you edit titles, etc. otsmid 1.0 For mass-writing of all of your files, however, this would be a tedious process. So we've created a command line tool called "otsmid.exe" (Ots Media ID). Run this from a command prompt and look at the output and instructions. Basically you can do something like: otsmid.exe myotsfile.ots set 1 bcms x7ACE ...and the Ots file will instantly be updated with appropriate feedback as to the success or failure of the operation. You can also read existing IDs from Ots files using this tool, as well as setting multiple IDs at once if the Ots file contains multiple items, eg: otsmid.exe myotsfile.ots set 10 bcms x7ACE x7ACF x7AD0 The above will set items 10, 11 and 12 to the specified IDs. The tool is smart and will not actually write to the file if the IDs you're setting are already set accordingly. The idea is you can call this tool from some kind of program you've written that attempts to set all IDs. You should always examine the output and return value (0 for success, 1 for error), and a line in the output which begins with "SUCCESS" or "ERROR", and further human-friendly text. Play with this tool from the command line and you'll soon get the idea. As always, make sure you operate only on COPIES of your Ots Media. It's imperative you ALWAYS have backups of all of your files. Although we're confident in this tool, we obviously can't provide any guarantees. There's always the possibility of bugs, corruption in your files from earlier system issues which causes weird behaviour, or faulty RAM or other hardware issues on the system you're running on. Of course this applies always to anything you do, using any tool, whether from Ots or elsewhere. OtsAV 1.94.029 Once you have mIDs in your files, or some subset for testing, you can use the OtsAV version we've provided (remember to do the "Easy Scan with Forced Refresh..." so OtsAV will "see" the new IDs). OtsAV now supports mIDs in all of the following ways: - mIDs, if defined, are displayed in the item pop-over (the window that instantly pops up as you hover over items in lists). - mIDs are displayed in the Album/Item Info dialog. - mIDs are written to CSV files when using the Export As CSV File option. - mIDs are written to CSV log files when using CSV format for logging. - mIDs are written to OFL files if you choose the new option "Export As Ots File List with Media IDs". This function will create an OFL file that writes a mID reference for each item if the mID is present, with fallback to the usual behaviour of a file.ots|item reference for any items that do not have a mID. These files can be imported back into OtsAV and will always identify the correct items regardless of filenames and file paths (as long as mIDs were actually used, of course, and you had unique mIDs as per discussion above). - The way that these mID references are written into this extension of the OFL format is very straight-forward. Each line for an item is simply in the format of @@<mID>, eg: @@x7ACE If the ID can't be resolved upon loading (doesn't exist or you haven't imported all of the appropriate media files), then as usual you'll get a placeholder directive. - OTM (template) files for the scheduling system work in the same way. You can now reference items by mID by using the @@<mID> format on a given line. - OMQL has been enhanced with the "mediaid" or "mid" (shorter version) operations. You can now do, eg. "mid = x7ACE" or "!mid unset" in all places where OMQL is used, including templates and directly in the Media Library interface. - Given the above, although you can now directly search for a specific item in the Media Library list by using OMQL (eg. entering "mid=31438" or "mid=x7ACE"), we've also created a shortcut that may be typed directly in the search field. This shortcut mirrors the @@ format used in OFL files. Instead of typing a (portion of) title/artist like "Beatles", simply type eg. @@x7ACE, and the item (or items if you have re-used that ID) will be displayed. Note that the @@ must be the first two characters typed and there mustn't be any spaces between it and the number. This is a great way to quickly bring up an item manually just from knowing its mID. Although not related specifically to mIDs, we've also added the following functionality which you will likely find useful: - The release info chunk for an item is now analysed during import, and the year component if present, is obtained and stored in the Media Library, and can be accessed/used in the following ways: - The year is displayed in the item pop-over. - The year is displayed in the Album/Item Info dialog. - OMQL has been enhanced with the "year" operation. You can now do, eg. "year=1986" or "year >= 1990 & year <= 1999" or "year unset" or even "year=99" or "year>12" (2-digit year format, which will be interpreted within the range of 1950 to 2049). Again, this works from all places where OMQL is available, including in scheduling templates. - As you likely already have release info chunks for all/many of your files, you can benefit from this immediately simply by using the "Easy Scan with Forced Refresh..." option and issuing some OMQL! A note on compatibility Although these extra things are being stored in the Media Library, we've been careful to ensure that the format has not changed for this release and therefore OML files saved from this version will still load and work fine in earlier OtsAV versions, albeit without the added functionality. The same is true of Ots files you modify by adding a mID to items within them. We always try and maximise compatibility as far as possible. Though this does obviously hold back many things we'd like to enhance and therefore we have to draw a line somewhere. Hence it's a good idea you start transitioning to the newer versions as best as you're able. It's also worth noting that, as always, many enhancements have been made and issues resolved. This version of Ots Studio is more stable than earlier versions (specifically, two bugs that could cause a crash in very specific scenarios have been squished - one involving the "Clean up title/artist" filter). And as always, we continue to make performance improvements - and these releases, both OtsAV and Ots Studio, are no exception. Re-indexing your mIDs Although the idea of permanent IDs sounds kind of, well, permanent - and therefore the inclination is that much thought must be put into how you generate and manage them - from an Ots perspective at least, you can re-index your IDs at any time you wish without causing any harm to your files. Obviously if you've built up a collection of lists that are all based on these IDs, then those would become useless if your IDs change, but that's fairly obvious and presumably you already have a pretty solid system for managing things, whether it be tree/folder based, or using a proper database system or the like. So don't be afraid to experiment, play and test. You can change your ID scheme later if the need arises. But certainly, the sooner you have a solid ID system/scheme in place, the sooner you can move forward and always just know that an "<org>:<mID>" reference is reliable and stable. The APIs we've been developing make extensive use of mIDs where available/appropriate, so having them in place is going to make things better for you.