Add-on:Cinema Experience

= About Cinema Experience =

History
This add-on has a lot of history. It started life in 2009 as the Home Theatre Experience script, written by an amazing and skilled Python programmer nuka1195. Through out its life it has brought many changes to XBMC. In December 2010, giftie took the reigns, and the script was modified to work with the new add-on engine in XBMC's Dharma. The name was changed, and the incarnation of Cinema Experience you know was born.

In the beginning, the script was only being maintained to function with XBMC. Then the script needed some functional repairs. Later, some major changes (and even some that brought about negative feedback). Now it's 2013, and XBMC Frodo is here. Cinema Experience is here to stay. Cinema Experience is currently maintained and improved by giftie. He's added numerous features to the script, and provides invaluable support via the XBMC forums.

What does it do?
The Cinema Experience script will add that WOW factor to your home theater, and give you a true Cinema Experience! Yes, you will still have to supply the popcorn and drinks. There's not much we can do about that. This script allows you to play trivia slides, movie trailers and other videos (intros and outros) that will help you get that Cinema Experience - just like at the local theater. Trivia slides can be any JPG or PNG image (many Movie Trivia, Stills, and Movie Fact packs already exist). The Feature Presentation Movie(s) must be in your Video Library. Cinema Experience can stream trailers, download them from Apple Movie Trailers, or play locally stored trailer(s) that are on your system or in your Movie Library.

What doesn't it do?
The Cinema Experience script will NOT work with any movies that are NOT local and scraped into your Movie Library. This means that any streaming content (let's use Netflix as an example, but this applies to any and all Video Add-ons that stream content to XBMC) either supported and in the official repository or not supported and in a third party repository will not work with the Cinema Experience script.

How do I get it?
At the moment, for XBMC Dharma and Eden this add-on is only available through installable ZIP files. The Frodo version has been added to the Official Official XBMC Repository, making it easier to get.

Dharma: Download

Eden: Download

Frodo: Available from the Official XBMC Repository

Reporting Bugs & Requesting Features
Cinema Experience is an evolving creature, getting better and more feature-rich with each release. That said, bugs happen. When they do, a bug report needs to be made. These are to be made on the Cinema Experience forum thread. A debug log is ALWAYS required, along with the steps needed to re-create the bug. I won't be able to help you if I can't understand what's happening.

Reporting Bugs: Method 1

Use the Debug Log Script.

Reporting Bugs: Method 2

Manually locate your xbmc.log file. Copy & paste your xbmc.log file to pastebin.com (or a similar site).

Note: If you feel that you have private information in your log file that you don't want the public be able to see, set up an account on pastebin.com and store it as a private paste.

Uploading Logs
 * 1) Put XBMC into Debug Mode.
 * 2) Restart XBMC.
 * 3) If you have add-ons that run automatically when XBMC starts, wait a few minutes for these scripts to run (ShareThe.TV, Weather.com Plus, etc.).
 * 4) Run Cinema Experience.
 * 5) Upload your FULL xbmc.log file to pastebin.com (or a similar site).
 * 6) Create a new forum message in this thread. Includethe  steps required to reproduce the bug and your pastebin.com URL.

Requesting Features

I accept feature requests in this thread. Be sure to be specific about what you'd like to see added.

= Information & Setup =

Supported Ratings Systems
Cinema Experience currently supports the MPAA, BBFC, FSK and DEJUS ratings systems. If you'd like a new rating system supported, post in this thread. You may need to provide a database file, or some screenshots of the table. I need to know each different rating in that column. What I need to see will depend on your database. If you are using the default database format (i.e. you haven't made any changes to XBMC) you can post the database file to Google Drive or Drop Box and then PM me a link to the file. If you are using MySQL, you will need to access it yourself (using a viewer of some sort) and send me some screenshots movieview table. Generally, column c12 contains the ratings.

The database you need depends on the OS you are using. This Wiki Page will help you find the proper file. The Video database is named MyVideosXX.db - with XX representing the database version. Use the one with the latest date.

Sequence Overview
Cinema Experience gives you the ability to enable or disable any introduction videos, or the trivia slideshow. You have the power to customize your cinema experience. The following is an example of the complete script flow:

'''
 * Trivia Intro Video(s)
 * Trivia Slides with Optional Music Playlist
 * Trivia Outro Video(s)
 * Movie Theater Intro Video(s)
 * Coming Attractions Intro Video(s)
 * Trailer(s)
 * Coming Attractions Outro Video(s)
 * 3D Intro Video(s) - if upcoming Movie is in 3D format
 * 3D Trailers( from folder as I haven't found a site that has them really available) - if upcoming Movie is in 3D format
 * Countdown Video
 * Feature Presentation Intro Video(s)
 * Rating Video (MPAA, BBFC and FSK ratings are currently supported)
 * Audio Format Video
 * FEATURE PRESENTATION
 * Intermission Video(s) (note)
 * Rating Video
 * Audio Format Video
 * FEATURE PRESENTATION 2
 * Intermission Video(s) (note)
 * Rating Video
 * Audio Format Video
 * FEATURE PRESENTATION 3
 * Intermission Video(s) (note)
 * Rating Video
 * Audio Format Video
 * FEATURE PRESENTATION 4
 * Intermission Video(s) (note)
 * Rating Video
 * Audio Format Video
 * FEATURE PRESENTATION 5 (end note)
 * Feature Presentation Outro Video(s)
 * 3D Outro Video(s) - if upcoming Movie is in 3D format
 * Movie Theater Outro Video(s)

'''

Available in 3D if upcoming movie is 3D and settings enabled

(note) At this point in the script, if multiple features have been queued and the skin uses home menu integration, multiple rating videos, audio format videos, features, and intermission videos will take the place of a single feature. A total of 5 features can be queued. This option can be even larger if you use one of the starting methods suggested in the Script Starting methods section.

Root Directory Structure
This is the suggested directory structure for all of your Cinema Experience content.



Audio Format Directory Structure
The only directories that need to be in a specific format are in the Audio Format directory. This is because the script uses the name of the Audio Format (DTS, Dolby Digital, etc.) to determine what video to play.



Intro & Outro Directory Structure
Even though these directories don't need to be in a specific format, it's a good idea to use the standard shown below. If you're having trouble, switch to the standard and reconfigure Cinema Experience for the new directory structure.



Trivia Directory Structure
Even though these directories don't need to be in a specific format, it's a good idea to use the standard shown below. If you're having trouble, switch to the standard and reconfigure Cinema Experience for the new directory structure. The example below shows some popular slide sets copied into the appropriate directory.



Trivia Slideshow Explained
The script can display a slideshow at the start of the experience. The slides can be standard still slides or Q&A(with clues). The best method of storing the slides are to have them in separate folders, the script can search the folders recursively.

Stills
Stills are trivia slides that only have one part, or are not multiple part slides like the Question & Answer slides. These slides do not require the use of a slides.xml file.

Q&A
Question & Answer slides have multiple parts (for example: Question, Clue, Answer). This type of slide does require the use of a slides.xml file to enable the script to determine how and when to display each Q&A slide.

XML File Explained
A Breakdown of the XML File

A Breakdown of ".([0-9]{1,3})+_q.jpg"

The "+_q" can be any letter or combination of letters as long as the pattern is kept. For example:

Example XML Files

This example of a slides.xml file is for a two part trivia question (Q&A) with words and ordering numbers (i.e. slidename1_q").

This example of a slides.xml file is for a two part trivia question (Q&A) without ordering numbers (i.e. slidename_q").

= Settings Explained =

Trivia Mode
Three(3) modes available: None, Slide Show and Movie Quiz Script.

None
No Trivia pre-show

Trivia Slideshow

 * Slide Show specific settings:
 * Duration(in Minutes): Set the total length, in minutes, of the slide show
 * Slides Folder: The parent folder of the slides
 * Show Question Slide for(seconds): The time, in seconds, that the question slide is displayed on the screen
 * Show Clue Slide for(seconds): The time, in seconds, that the clue slide is displayed on the screen
 * Show Answer Slide for(seconds): The time, in seconds, that the answer slide is displayed on the screen
 * Show Still Slide for(seconds): The time, in seconds, that the still slide is display on the screen
 * Play Music during Slide Show: Enabling this settings the script will play music during the slide show
 * Music Mode: Two modes available, Music File/Playlist or Music Folder
 * Music File/Playlist: Select the music file or playlist that is played during the slide show. Only standard playlist(.m3u, .pls, .asf, .ram) are allowed(no SmartPlaylist)
 * Music Folder: Select the folder which to play music from during the slide show
 * Adjust Volume during Slide Show: Enabling this setting allows the script to drop the volume level during slide show
 * Music Volume Level: Set the volume level(0-100)
 * Fade Volume at end of Slide Show: Enabling this setting allows the script to fade the volume down, then back up at the end of the slide show
 * Fade time in seconds: Set the fade time in seconds
 * Select Only Unwatched slides: Enabling this setting tells the script only to use unviewed slides. The script will automatically reset the watched status during the slide show if slides run out before the end of the slide show
 * Reset Slide watched status: Manually reset the watched status of slides
 * Limit Slides by movie rating(requires slides.xml): Enabling this setting informs the script to limit the slides to a maximum MPAA rating of the movie. Other movie rating formats are roughly assessed and matched to MPAA Ratings
 * Rating Limit for Trivia(requires slides.xml): If the previous setting is not enabled, adjusting this setting will fix the MPAA level of the slides used in slide show

Movie Quiz Script
Use the Movie Quiz Script in place of the Slide Show

Common Settings to the two trivia modes

 * Intro Video: Enabling this setting will play Intro video(s) before Trivia
 * Single Video: Select a video to play, this also can be a playlist file(.m3u, .pls, .asf, .ram)
 * 1 Random Video: Select a folder to play a single video from, randomly selected
 * 2 Random Videos: Select a folder to play a two(2) videos from, randomly selected
 * 3 Random Videos: Select a folder to play a three(3) videos from, randomly selected
 * 4 Random Videos: Select a folder to play a four(4) videos from, randomly selected
 * 5 Random Videos: Select a folder to play a five(5) videos from, randomly selected
 * Outro Video: Enabling this setting will play Outro video(s) at the end of the trivia
 * Single Video: Select a video to play, this also can be a playlist file(.m3u, .pls, .asf, .ram)
 * 1 Random Video: Select a folder to play a single video from, randomly selected
 * 2 Random Videos: Select a folder to play a two(2) videos from, randomly selected
 * 3 Random Videos: Select a folder to play a three(3) videos from, randomly selected
 * 4 Random Videos: Select a folder to play a four(4) videos from, randomly selected
 * 5 Random Videos: Select a folder to play a five(5) videos from, randomly selected

Miscellaneous
= Integration =

home_automation.py
When the script runs for the first time, the script will copy a folder named ha_scripts and it's contents to your userdata\addon_data\script.cinema.experience folder. Inside that folder is a file named home_automation.py, which is a python script that Cinema Experience will trigger. Here is were the coding begins. It may seem intimidating, but it's actually fairly simple. Edit home_automation.py in a text or script editor. Beginning on line 53 of the file, you will notice commented parts of the code that say # place code below this line, example shown below in bold text.

This line is where we will start. For those not familiar with python, lines beginning with '#' are comment lines. To get the information to EventGhost, we need the script to send a broadcast. On XBMC Version Eden and Dharma, we used to use the xbmc.executehttpapi function. Frodo and newer, HTTP API had been removed. Now the script includes it's own UDP Broadcaster. The home_automation.py script module already imports the utils module, all that is need it to used the utils.broadcastUDP function.

The broadcast we need to send from Cinema Experience is something that we can easily identify and distinguish in EventGhost. For this example we will use "CE_Automate". We will also use the html    tag to start the broadcast, and    to end the broadcast, as well as    to separate the trigger. For example:

Now let's put it into the code, but first a little tip about the indentation. Python really likes indentation, in fact it will not work and throw a fit if the indentation is not correct. The script uses 4 spaces per indentation, these are also not tabs. The code we insert will need to line up with the other indented lines. For example:

Now, when the script starts, it will broadcast:

EventGhost Setup
Now we need to turn our attention to EventGhost. Install the XBMC Event Receiver plugin found here and setup with these settings(use the IP 127.0.0.1 if EventGhost is on the same machine as XBMC, otherwise use your XBMC IP address).

The triggers we need to look for are the messages that we have broadcast from Cinema Experience. The XBMC Event Receiver prefixes the broadcast with XBMC-Event., so the event we will be looking for messages like this:

So now we can create a macro, and use  as the event, then add what you want EventGhost to do when this event occurs. If the script senses that the playback has stopped (by pressing stop, video crash, etc.) it will trigger the script_end trigger.

Script Triggers
Here are a list of the triggers that are available:

Skin Integration
Skin developers can now seamlessly integrate Cinema Experience! Often the chosen location for such integration is in the DialogVideoInfo.xml file. There are two methods, the old way and the new Movie ID way. Choose the method for your platform.

Script Starting Methods
There are a few different arguments available to change the starting the script. This are mostly for starting from with-in a skin or from an outside source(remote). Each cause the script to behave differently.

Using the built-in RunScript Method  often used in skins and keymaps 
 * RunScript(script.cinema.experience,argument)

Using the JSON RPC Method
 * {"jsonrpc": "2.0", "method": "Addons.ExecuteAddon", "params": { "wait": false, "addonid": "script.cinema.experience", "params": [ "arguments" ] }, "id": 1}

Window ID
This is primarily used to put the script into multiple feature mode, though it can be used for a single Movie. The user will need to queue the movies into a playlist(normal queuing methods are used, Q on a keyboard, 0 on a remote or from the context menu)

Possible window IDs to use:
 * movietitles
 * moviegenres
 * movieyears
 * movieactors
 * moviedirectors
 * moviestudios
 * moviesets
 * moviecountries
 * recentlyaddedmovies

These match the general quick library links available from the homepage.

eg.
 * RunScript(script.cinema.experience,movietitles)

This will open up the library using Movie Titles, with the script waiting for the set number of features to be queue.

Movie ID
This is a new method introduced in version 3.0.1 of the script, to replace the former method of starting the script from a skin. The former method(no arguments sent to the script) caused an unsightly jump in the Movie Library list. This was due to the method XBMC uses to queue a video. With Frodo, skins now can extract the database ID for the Movie(using $INFO[ListItem.DBID] ) This method also allow a known database ID to be sent. Multiple database IDs can be sent at the same time, causing the script to go into Multiple Feature mode(fixed in version 3.0.4). The database IDs need to be separated by a semi-colon

eg.
 * RunScript(script.cinema.experience,movieid=$INFO[ListItem.DBID]) skin method


 * RunScript(script.cinema.experience,movieid=35) single movie database ID
 * {"jsonrpc": "2.0", "method": "Addons.ExecuteAddon", "params": { "wait": false, "addonid": "script.cinema.experience", "params": [ "movieid=35" ] }, "id": 1}


 * RunScript(script.cinema.experience,movieid=35;123;112) multiple movie database IDs
 * {"jsonrpc": "2.0", "method": "Addons.ExecuteAddon", "params": { "wait": false, "addonid": "script.cinema.experience", "params": [ "movieid=35;123;112" ] }, "id": 1}

= FAQ =