• What Is a Mediascape?
• Download Mscape Suite
• Browse Mediascapes
• Blog

TWiki > Main > ConvertingMobileBristolMediascapes

Converting Mobile Bristol mediascapes

As mediascapes are a relatively new medium Hewlett Packard are continually striving to improve the tools and facilities for creating and playing them. The drawback with this is that as the mscape maker and the mediascapes that it produces become more sophisticated the older mediascapes made with earlier versions of the mscape maker no longer work correctly.

If you are a frequent user of computers for other things you may be familiar with this situation with such things as importing word processor documents into newer versions of the word processor.

Fortunately, it is possible to convert the older mediascapes so that they become new mediascapes. The new mscape maker has been designed to do as much of the conversion for you, however it cannot do everything and so in some cases there are certain items that will need your input in order to be correctly converted.

The conversion process

When you import an older Mobile Bristol Mediascape into the new mscape maker much of the conversion happens automatically. However, not all of it does and there are three areas where you may have to intervene to ensure that the conversion process has been successful.

To import a mediascape you do the following

Firstly, the conversion process is as thorough and as fail safe as it can be, but, as with any computer based activity, it is a good idea to make a back up copy before you start doing anything, just in case.

From within the mscape maker select File and choose the Convert MB menu option.

Choose the mediascape you want to import and convert. A warning message will appear alerting you to the conversion.

If you go ahead with it then the conversion is carried out and the new version of the mediascape is created and saved with the extension ‘.msl’.

When the conversion is finished a report box will appear indicating the success of the conversion.

The mediascape is now converted and is ready for further editing.

You may have to make adjustments by hand in the following situations:

Rewriting of event scripts

The automatic conversion process does its best to convert the event scripts. This conversion is difficult and thus what takes place is a best guess at conversion. The original script is enclosed in comments along with the best guess conversion and then the user must amend them. Basically in the comments it says; ‘This is what you had originally, and this is roughly what I think it should be now’.

For example where an event script in a Mobile Bristol mediascape may have been this:

<if cond="inRegion(regions$frog) and variables$frog=0">
<then>
<playMedia media="media$frog" volume="100" loop="false" position="0" fade="0" delay="0"/>
</then>
<else>
<DisplayHTMLImage source="'frog.jpg'" tag="'ImageTag'" background="'88aaff'"/>
</else>
</if>

After conversion it will appear as this:

/*
*************************************************************
The handler code in Mobile Bristol format looked like this:
*************************************************************
<if cond="inRegion(regions$frog) and variables$frog=0">
<then>
<playMedia media="media$frog" volume="100" loop="false" position="0" fade="0" delay="0"/>
</then>
<else>
<DisplayHTMLImage source="'frog.jpg'" tag="'ImageTag'" background="'88aaff'"/>
</else>
</if>
*************************************************************
For the current version, try this instead:
*************************************************************
if (frog_reg.IsInside && frog_var.Value == 0)
{
frog_audio.Volume = 100; // May not be needed. Check the values of the properties on this object.
frog_audio.Loop = false; // May not be needed. Check the values of the properties on this object.
frog_audio.FadeDuration = 0; // May not be needed. Check the values of the properties on this object.
frog_audio.Play();
}
else
{
frog_image.Show();
}
*/

Such scripts can either be sorted out ‘by hand’ and re-written using the new style of scripting with reference to the ‘phrase book’ below.

Alternatively, you can remove the entire script and generate the new scripts by doing drag and drop operations within the mscape maker.

What happens during the conversion?

For completeness it may be useful to know some of the steps that take place during the conversion although it is not vital that you understand this in order to carry out conversions. The mscape maker creates a MapLib file for the mediascape and links it into a place object, adding any regions and speakers in the original mediascape. A content folder is created and all the referenced content files are moved there. If required, a web root folder is created and all HTML pages are moved there.

The original .mbw, .mbp and .mbs files that made up the mediascape are moved to an Archive sub-folder. Any deprecated objects (such as notifications and functions) are copied to a .del file in the Archive sub-directory.

MSL

The Mobile Bristol scripting language was based on something called XML, this meant that all parts of it were enclosed in ‘pointy brackets’, the new scripting language is called MSL, which stands for ‘Mediascape Scripting Language. MSL structures mediascapes into four sections:

Sensors, which are used to hold information about sensors used to trigger contextual events, such as GPS.

Media, used to hold the audio, images, videos etc, that are used in the mediascape.

Tools, to hold useful functions, for example the Playlist and the Logger.

State, used to hold variables.

MSL is based on a language called C sharp (see below) so there are curly brackets, but a lot less of them than with Mobile Bristol scripts.

Here is a snippet of Mobile Bristol script:

 <if cond="variabls$count = 1">
   <then>
      <playMedia media="media$frogs" volume="100"/>
   </then>
   <else>
   </else>
 </if>

and here is the same snippet converted to MSL script:

if (count.Value == 1)
 {
   frogs.Volume = 100;
   frogs.Play();
 }

MSL and other languages you might be familiar with

C# has strong influences from languages like C++, Java and Delphi, so if you have some familiarity with any of those you may recognise elements in C# and thus the MSL used in mediascapes. The syntax of MSL also has a few similarities with the syntax of Flash ActionScript and Javascript so again some familiarity with these may come as an advantage when dealing with MSL.

Things to note with MSL

There are less terms and not every term in the script is enclosed in brackets, so it is a lot easier to write.

You don’t have to state where things like media resources are coming from so you can say ‘frogs’ instead of having to say ‘media$frogs’.

Actions and attributes of objects like media resources are refereed to in terms of the object that they relate to. So to play ‘frogs’ with a certain volume in Mobile Bristol scripting you used to say:

<playMedia media="media$frogs" volume="100"/>

In effect; ‘I want to play something, this is what I want to play and this is how loud I want to play it’. With MSL you now say:

 frogs.Volume = 100;
 frogs.Play();

Here you are saying; ‘Set the frog’s volume to this’ then ‘Play the frogs’.

MSL 'Phrase book'

If you are used to writing scripts in Mobile Bristol then this section shows the terms you will be used to and how they should be done within MSL. 'Manual page' refers to the Mobile Bristol Manual which you may already be familiar with if you are programming in the Mobile Bristol environment.

Using actions

<playMedia media="media$harp" volume="100" loop="false" position="0" fade="0" delay="0"/>

harp.Volume = 100;
harp.Loop = false; 
harp.FadeDuration = 0;
harp.Play();

<stopMedia media="media$harp" fade="0" delay="0"/>

harp.FadeDuration = 0; 
harp.Stop();

<setMediaVolume media="media$harp" volume="50" fade="0" delay="0"/>

harp.Volume=50;

<stopAll fade="0" delay="0"/>

Audios.StopAll();

<setVolumeAll volume="75" fade="0" delay="0"/>

n/a

Source actions

<playSource source="sources$source1" volume="100" loop="false" position="0" fade="0" delay="0"/>

source1.AutoPlay = true;

<stopSource source="sources$source1" fade="0" delay="0"/>

source1.AutoPlay = false;

<setSourceVolume media="sources$source1" volume="100" fade="0" delay="0"/>

n/a

Image actions

Image display in Mobile Bristol was rather sparsely supported with a single action. This maps indirectly onto one of the rich new image capabilities in mscape.

<DisplayHTMLImage source="'coins.jpg'" tag="'ImageTag'" background="'88aaff'"/>

coinsImage.Show();

URL actions

URL actions in Mobile Bristol allowed local audio files to be played without needing a corresponding media object. This capability is not supported in mscape.

<playUrl url="'files\mySound.mp3'" alias="'mysound'" volume="100" loop="false" position="0" fade="0" delay="0"/>

n/a

<stopUrl alias="'mysound'" fade="0" delay="0"/>

n/a

<setUrlVolume alias="'mysound'" volume="75" fade="0" delay="0"/>

n/a

Debug actions

It was possible to trace a text message to file in Mobile Bristol. In mscape this capability is provided by the Logger object.

<trace text="'Hello World'"/>

Logger.Log("Hello World");

<setTraceLevel level="5"/>

n/a

Logic actions

Mobile Bristol only supported one form of flow control - conditional expressions using the if-then-else pattern.

<if cond="variables$count = 1">
  <then>
     <playMedia media="media$frogs" volume="100"/>
  </then>
  <else>
  </else>

</if>

if (count.Value == 1)
{
  frogs.Play();
}

<set var="'variables$var1'" value="123"/>

var1.Value = 123;

Flash actions

sendFlashMessage(‘FUNC’,'updateScore',200 )

flashMovie1.RunActionScriptWithParams("updateScore",200)

HTML actions

<NavigateHTMLPage source="'files\newpage.html'"/>

WebPages.LoadUrl('files\newpage.html');

Event actions

In Mobile Bristol it was possible to simulate the effect of a change in the user's location. This is no longer possible.

<raise event="events$mbLocationChangedEvent" x="11" y="22"/>

n/a

Functions

Functions in Mobile Bristol are used to return a value that can then be included in an expression. For example, the function inRegion might be used as follows:

 <if cond="inRegion(regions$myRegion)">
   <then>

      <trace("'In region'")/>
   </then>
   <else>
   </else>
 </if>

In mscape, many, though not all, of these functions are now implemented as read-only properties on the appropriate object. So, the previous example might be written:

 if (myRegion.IsInside)
 {
   Logger.Log("In region");
 }

Standard translations for the MB functions are listed below:

Region functions

enteredCount(regions$myRegion)

myRegion.EnteredCount

inRegion(regions$myRegion)

myRegion.IsInside

Media functions

getMediaPosition(media$story) > 2000)

story.Played

getMediaMaxPosition(media$story) > 2000)

n/a

isMediaOn(media$story)

(story.Playing || story.Paused)

isMediaPaused(media$story)

story.Paused

isMediaPlaying(media$story)

story.Playing

isMediaFading(media$story)

story.Fading

URL functions

Because it is not possible to play audio files directly in mscape, none of the associated URL functions are supported.

getUrlMaxPosition(alias)

n/a

getUrlPosition(alias)

n/a

isUrlOn(alias)

n/a

isUrlPaused(alias)

n/a

isUrlPlaying((alias)

n/a

isUrlFading(alias)

n/a

Source functions

It is not possible in mscape to express functions on a speaker related to its associated audio object. These calls will need to be rewritten as accessing the associated audio object's properties.

getSourceMaxPosition(source)

n/a

getSourcePosition(source)

n/a

isSourceOn(source)

n/a

isSourcePaused(source)

n/a

isSourcePlaying(source)

n/a

isSourceFading(source)

n/a

Location functions

Mobile Bristol had an implicit model of the user's unique location which could be accessed by the functions below. In mscape, the user's location is only known during a Place object's OnLocationChanged event. If the last location is needed later, the author should save the current location in state variables during the event handler, eg:

myX.Value = x; 
myY.Value = y;

getUserLocationX()

n/a

getUserLocationY()

n/a

Random function

Allows a random number to be generated in the interval from min to max inclusive. In mscape, this capability is provided by the library object Random which must be created before use.

rand(0, 2)

(new Random()).Next(0,3)

Changes if you use Flash movies

If your mediascape includes a Flash movies then you will have to do the following.

Make changes to the original Flash file and re-publish as a new Flash movie

Include the Flash movie into the new mediascape

Rewrite parts of the Flash ActionScript and mediascape scripts if required

Make changes to the original Flash file and re-publish as a new Flash movie

Copy the mediascape.as file into the same directory as the Flash file. (You can find the ‘mediascape.as’ file in the help file under; ‘User Interfaces - Adobe Flash’. It is linked to under the heading ‘Allowing Communication with the Mediascape’.)

Change the include line in the Flash ActionScript from:

#include "mb.as"

so that it includes this new include file, like this:

#include "mediascape.as"

Publish a new Flash movie from this file.

If your Flash file has ActionScript that passes data to the mediascape then you will need to change this before publishing the movie. See below for more on this.

Include the Flash movie into the new mediascape

Add the new Flash movie object by right clicking on the media object in the left hand bar of the mscape maker. Then give the file name of the Flash movie when prompted for it.

Rewrite parts of your scripts if required

If you use scripting on either the Flash movie side or the mediascape side to communicate then you will need to change this as follows:

If you have used ActionScript to send data from the Flash movie to the mediascape then:

In the ActionScript you will have statements to send data like this:

sendXML("one", "two");

In order to work in MSL these should be changed to look like this:

fscommand("one", "two");

When you do this from within the ActionScript of your Flash movie you have to have a corresponding bit of script in the mediascape to listen out for the arrival of data being communicated in this way. This too has changed to that the old mediascape script event called:

mbFlashEvent

should be replaced by the new event:

OnFsCommand

If you have used scripting in the mediascape to send data from the mediascape to the Flash movie then:

In the mediascape script you will have calls like this:

sendFlashMessage("FUNC", "updateGPS", "fixed");

Where FUNC declares that you are calling a function, the ‘updateGPS’ is the name of the function and ‘fixed’ is the parameter that you are passing to this function. In the new MSL script in the mediascape you will need to replace such calls with:

mymovie.RunActionScriptWithParams("updateGPS", "fixed");

Or

mymovie.RunActionScript("updateGPS");

Here ‘mymovie’ is the name of the flash movie object. In order to do this you will need to know the name that you gave to the Flash movie object when you imported it (as above), this is usually the name of the Flash movie file, although you can change what it is called within the mediascape if you want to.

The actual script that forms the function being called (‘updateGPS’ in this case) does not need to be changed at all.

Possible changes due to HTML-page problems

Find out if you have you got HTML problems

If you have used HTML in your mediascape then there is a chance that you will have problems with the conversion. To find out if you have problems you need to view your HTML homepage (on the mobile device or in the mscape tester) and check the following:

If the page included images or Flash files confirm that they are there in the new converted version.

If the page had links to other HTML pages confirm that these links work by clicking on them.

If there are problems with either of these checks then it means that the conversion process was not able to copy all the parts of your HTML to the new mediascape and you will have to copy these parts yourself.

Copying missing parts of HTML

The missing files are files that are in the Mobile Bristol mediascape but that have not been copied to the new mscape mediascape. You have to find them in your Mobile Bristol folders and copy them to your mscape folders making sure that they are in the same place relative to the HTML home page.

Find the directory where the files are

When you created your Mobile Bristol mediascape you were asked to say where you wanted to save it to. The standard place is on the desktop in ‘My Documents’ in a folder called ‘My Mobile Bristol Projects’, but you might have specified a different location. You were also asked to give the mediascape a name. This name was then used for the folder that contained all the assets for the mediascape. So if your mediascape is called ‘mymediascape’ and you used the standard location then you should look for a folder called:

‘My Documents/My Mobile Bristol Projects/mymediascape’.

Find the files to be copied

The missing files should be in this folder or in a sub-folder (a folder within this folder). If they are in a sub-folder then you will need to copy the whole sub-folder.

If you can’t remember all the files, then have a look at your HTML home page. It will have been copied unchanged to the new mscape mediascape but you can still see the Mobile Bristol version in your mediascape directory it will have the name that you gave it when you created it. If you open it up to look at the links to external assets (such as images, Flash movies or other pages) it will show you what files you need to copy over and where they are in relation to the HTML home page.

Copy them to the new directory

When you converted your Mobile Bristol mediascape and saved it you gave it a name (for example ‘mynewmediscape’). The folder that you saved it too is where you want to copy the missing files to. In this folder there will be a file called ‘mynewmediscape.msl’ and a folder for the content called ‘mynewmediscape_content’. In this content folder is a folder called ‘Web Pages’ containing the copied HTML home page. This is your starting point for copying the files.

Make sure they stay in the same relative positions

In the Mobile Bristol mediascape folders the missing files all had a certain relationship with the HTML home page in terms of their location. You need to copy them over so that they maintain this relationship.

Thus, if the file was in the same folder as the home page then it needs to be copied over so that it is in the same folder as the copy of the home page in the ‘Web Pages’ folder described above.

Imagine if the file is in a folder called ‘cat-pages’ in the same folder as your HTML home page, then in the folder that your HTML home page was copied to you need to create a new folder called ‘cat-pages’ and copy the file in question into it.

You can confirm that you have copied all the pages to the correct places by performing the check described at the beginning, but this time perform it more extensively by visiting all the files that the home page links to.

If you had an HTML home page in a sub-directory...

When you were creating your Mobile Bristol mediascape the usual place to put your HTML home page is in the ‘mymediascape’ folder as described earlier. However, you could have put it in a sub-folder. If this is the case the conversion process will have copied this sub-folder and all of its contents, and the only reason that it won’t be working as expected is if one of the HTML pages links to a file that is outside the sub-folder. The process for copying the files is the same, the only difference being the location of the HTML home page.

Having problems?

If you are struggling with this operation then it may be worth contacting someone in your organisation who is more familiar with moving files around, for example the person that set your computer up.

Background information

This information is not vital but it may be useful if you need to deal with any other issues that may arise.

With Mobile Bristol you could specify one special HTML home page as a start page, and this page could then link to other pages if required.

With mscape mediascapes HTML pages are better integrated into the overall model. You can have many HTML pages and they are treated the same way that other media types are treated. Just as audios and images are grouped together in the left hand column of the mscape maker so too is there a place where HTML pages are grouped together.

When the conversion process sorts through a Mobile Bristol mediascape it converts this special case HTML page into one HTML page object in the mscape mediascape. It also adds a ‘show’ instruction in the ‘onLoaded’ event in mediascape so that the result exhibits the same behaviour as the Mobile Bristol mediascape, but now it is mimicked in the new mscape environment.

Ask the Mscape Community

Forums