Media Types

A Media Type is a data record inside PinballY that describes, in concrete programming terms, one of the media items that PinballY displays in its various windows. There are media types defined for the main background media displayed in the different windows (playfield images and videos, backglass images and videos, etc), and for several types of supplemental media, such as advertising flyer images, instruction cards, and game wheel icons. To a large extent, the built-in media types correspond to the standard media found in the HyperPin media packs distributed on the virtual pinball sites.

In addition to the pre-defined media types that the system uses in its own windows, Javascript code can define additional, custom types. This is done via GameList.createMediaType(). Custom types are useful with custom media windows - new windows that you create through Javascript code, which appear alongside the standard windows and can perform the same function of displaying a particular kind of media associated with the selected game. Custom media types and custom media windows work together by letting you add new kinds of windows that act very much as though they were part of PinballY's standard window set. You can also use custom media types for other purposes, such as adding new kinds of files for use in custom graphics.

Built-in media types

Here's a list of the pre-defined media types built into PinballY. The ID gives the identifier that you use to refer to the media type in Javascript functions, such as gameInfo.resolveMedia() or mainWindow.createMediaWindow(). The Menu order gives the sorting order when media types are listed in system menus; the media types included in a menu are arranged in ascending order of the Menu order number.

Custom media types

You can use Javascript to create your own custom media types, adding to the types that PinballY knows about out of the box.

To create a custom type, you call GameList.createMediaType(desc). desc is a descriptor object with properties that describe the new media type.

Here are the properties you can use in the descriptor object desc. All of these are required except for the ones marked as optional. An error will be thrown if any of the required properties are missing or use an invalid format.

• id: A string giving the media type an ID that you'll use to refer to this type in subsequent Javascript operations involving media types. For example, this is the ID you use to refer to this media type when calling mainWindow.createMediaWindow(), in the backgroundImageMediaType and backgroundVideoMediaType properties of the window descriptor.

  The only requirement for this type string is that it must be unique, so be sure it doesn't match the ID of any of the pre-defined types (see Media Types for the full list) or any other custom type you're using elsewhere in this script or any other scripts you're using.

• configId: A string giving the ID for this media type to use in the settings file. Like the id, this must be unique across all media types, since it has to uniquely identify the type when referenced in the settings file. This identifier also has some limits on its syntax: it must not contain any spaces or punctuation marks except for periods, hyphens, and underscores.
• name: A string giving the friendly name to use for the media type when displaying it in a menu or elsewhere in the user interface. This can be anything you like, but something descriptive is of course ideal. The system types render their display names in "title case" and in the plural, such as "Playfield Images" or "DMD Videos", so using a similar format will make your custom types harmonize better with the system types whenever they appear alongside them.
• menuOrder: A number giving the placement of this item in menus where media types are listed. Media types are arranged in ascending order of the menuOrder number when displayed in menus. See MediaTypes for a list of the pre-defined types and their assigned menu order codes. This is optional; if omitted, the system will assign an arbitrary order number that's higher than that of any of the built-in types.
• folder: A string giving the name of the sub-folder within the media folder tree where files of this type can be found. This is the name of a Windows disk folder, so it has to conform to the usual Windows rules about file naming (for example, a number of special characters are forbidden, including quote marks, slashes, question marks, and asterisks). This should be a plain folder name without any disk drive or path prefix, such as "Side Art Images". PinballY combines this with the standard media tree path to get the full path.

  See Files & Folders for details about how PinballY constructs full media path using this folder name. The folder string defined here corresponds to the <Media type subfolder> portion of the full path in the explanations in that section.

• perSystem: A boolean (true/false) value indicating whether there's a separate version of this type of media file for each game player system (Visual Pinball, Future Pinball, etc), or if there's a single global copy that applies to all systems. true means that the files are stored individually for each game system, and false means that the files are "generic", with only one copy that's shared across all of the game systems. The difference is described more fully in Files & Folders. Optional; defaults to false (making the media type "generic").
• format: A string indicating the broad format class that this type of media belongs to. This must be one of the following, exactly as listed (including capitalization):
  • "Image" - a still image, such as a JPEG or PNG file
  • "SilentVideo" - a video without any audio track
  • "Video" - a video with an audio track
  • "VideoWithAudio" - same as "Video"
  • "Audio" - an audio-only track, such as an MP3 or WAV file
• extensions: A string with a list of filename suffixes (extensions) to search for when looking for files of this type. List multiple extensions by separating each with a single space character. Each extension must start with a period ("."). For example, for image files, this might look like ".jpg .jpeg .png .apng .gif".
• hasDropButton: A boolean (true/false) value indicating whether or not a "Drop File Here" button should be displayed in the main playfield window when dragging a file over the window. If you plan to create a custom media window based on this type, you probably don't want a drop button for the type in the main window, since you can drop media of this type directly on the dedicated custom window instead; that's more intuitive and avoids cluttering the main window. If instead you intend for this type to be used for auxiliary purposes, rather than as a whole window backdrop, there won't be any "natural" place to drag and drop files of this type, so a main window button is useful. This is how the built in Wheel Icon and Table Audio types work, since they don't have windows of their own where they could otherwise be dropped. The default is false (no button) if the property isn't specified.
• rotation: For images, this specifies the rotation that should be applied when loading the media files, in degrees clockwise. This must be one of 0, 90, 180, or 270. This is primarily for the sake of the convention used in all HyperPin media packs to store playfield images and videos rotated so that the bottom of the playfield appears at the left side of the image.

  This is optional; if omitted, a rotation of 0 is used, which renders the media as it appears in the file. 0 degrees is the right setting for almost all media files except for playfield images and videos, which use the HyperPin convention.

• isIndexed: A boolean saying if this is an "indexed" media type, meaning that it might have multiple copies of the item for the same game, with numeric suffixes (1, 2, 3...) on the filename. This is the convention used in HyperPin media packs for Instruction Card media, where you might have files named "Sinbad (Gottlieb 1978) 1.png", "Sinbad (Gottlieb 1978) 2.png", etc. Optional; defaults to false.
• pageFolders: An array of strings, giving the names of subfolders of the media type's main folder (the one named by the folder property) used to store "pages" of the media. This is how the "Flyers" (scans of the original advertising material) in HyperPin media packs are organized. None of the other built-in media types apart from Flyers use this; all of the others just use a single file with no additional "page" structure (except for Instruction Cards, which uses the "indexed" scheme described above under the isIndexed property). Optional; if not provided, the media type simply uses a single file per game, without any added "page folder" tree.
• captureStartConfigVar: The name of the configuration variable (used in the Settings.txt file) where the trigger mode to use to start image/video capture for this media type is stored. As with all configuration variables, this should be limited to alphanumeric characters and periods, hyphens, and underscores. Optional.
• captureStopConfigVar: The name of the configuration variable where the trigger mode to end video capture for this media type is stored. Optional.
• captureTimeConfigVar: The name of the configuration variable where the video capture time for this media type is stored. Optional.

Calling the method creates a new media type based on the descriptor, and adds it to the system's internal list of types. You can use it from Javascript from that point forward by referencing the id string you provided.

The method has no return value. This might seem a little strange, since "creating" something usually returns an object representing that thing. In this case, there's no Javascript object representing the newly created media type; a media type is just an internal list entry within PinballY. In Javascript contexts where you need to refer to a media type, you do so using the id string you provided in the descriptor.