Script: My Music Box - Basic Edition

[Black Tulip] My Music Box (Basic Edition) - for Builders

(c) 2012 Auryn Beorn

My Music Box (Basic Edition) in Marketplace.

Thank you for having considered this script to enhance the quality of your products. Please read the following instructions carefully, especially the ones explaining which permissions to apply to the scripts for the next owner. Failure to complete this task INVALIDATES the license governing your use of this set of scripts. Should you have problems, please fill the scripts assistance form, explaining what you did and what happened, and I'll get back to you.

TABLE OF CONTENTS

• FEATURES
• SET UP
  
  • WHAT SCRIPT TO USE?
  • CHANGE PERMISSIONS FOR NEXT OWNER
  • EXAMINING THE SAMPLE OBJECT
  • FORMAT OF THE DESCRIPTIONS
  • HOW TO SET UP THE SPINNING PARTS
  • THE CONFIGURATION NOTECARD
• WHERE DO I PURCHASE SONGS?
• THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT

FEATURES

• Notecard configuration for the songs
• It allows each song having different sample duration (i.e., a song may have its samples being 9.5 seconds and another song have its samples being 9.8 seconds)
• Many songs and spinning prims can be safely included (check below)
• Volume is changed via menu
• Menu timeout to reduce lag - no open listeners after timeout (0.001 ms script time when idle)
• Final user can change access to owner only/everybody/group
• Menu can be integrated into tools such as MLPv2, AVsitter... (AVsitter version 2 works too!)

Although one would never require the 256 prims a linkset may have, to spin, if we reach this (very) extreme value, we may still add safely up to 50 songs. But normally, we will not need to use more than 20 prims spinning, so in this case, we may add safely up to 100 songs. The rule is simple: the more prims spinning, the less available memory for songs, and the reverse.

SET UP: WHAT SCRIPT TO USE?

There are two scripts contained in your folder:

[Black Tulip] My Music Box - Basic Edition
[Black Tulip] My Music Box - Basic Edition [MODULE]

We need to use ONLY ONE of them in a given product.

Which one? How to choose?

The [MODULE] version, as explained in the THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT section, will allow you to use this script integrated with other scripts that allow sending linked messages, such as the Multi Love Pose (MLP) or AVSitter for multiavatar, multianimation devices.

So, depending on what we need, we'll use the following script as main one:

Normal use - We want the menu to show when the object is clicked:
[Black Tulip] My Music Box - Basic Edition

The menu should show up after clicking a button from another script, like MLP, AVSitter:
[Black Tulip] My Music Box - Basic Edition [MODULE]

Once we've chosen the right main script, we have to set some descriptions in the primitives of the object, following the instructions below.

SETUP: CHANGE PERMISSIONS FOR NEXT OWNER

Check the following section on this page, knowing that each [Black Tulip] ASSET refers to the following scripts:

[Black Tulip] My Music Box - Basic Edition
[Black Tulip] My Music Box - Basic Edition [MODULE]

SETUP: EXAMINING THE SAMPLE OBJECT

Rez the sample [Black Tulip] My Music Box - Sample Object from your box. It will load the configuration and output owner-say messages like the following (memory report for yours may vary):

[15:30] [Black Tulip] My Music Box - Sample Object: Reading configuration notecard...
[15:30] [Black Tulip] My Music Box - Sample Object: Read configuration: Done. Free memory for the script: 29910 bytes

Once we read the Read configuration: Done, we may proceed to click the object in order to bring up a menu.

So, click it. As soon as you click it, you have a menu showing with the following options:

[Prev Song]    [Stop/Play]    [Next Song]
[Pick Song]    [Volume]       [*RESET*]
[Access]       [---]          [Close]

Using this is very simple. Clicking Stop/Play, the current song will start/stop and IF there are spinning parts defined (as the documentation explains below), the spinning parts will move when the song is playing, and stop once the song finishes.

By clicking Prev Song we change the current song to be played upon click Stop/Play to the previous one in the list (and if there was a song playing, it will stop to let this previous one begin.)

Next Song has the same effect but to change to the next song on the list.

*RESET* will ask us for confirmation to reset the script. Only the owner of the object is able to perform this operation.

By clicking Pick Song we get to a secondary menu that will show a list of songs and some information about each song, and buttons that are simply numbers to let us choose one song from the list.

By clicking Volume we get the following secondary menu to change the volume of the sounds played:

[Off]    [10%]    [25%]
[50%]    [75%]    [100%]
[^Up]    [---]    [Close]

Then finally by clicking Access in the main menu we get the following menu, which allows us to change who will be able to access to the menu and thus pick a song, play/stop them and change the volume:

[Everybody]    [Owner only]    [Group]
[^Up]          [---]           [Close]

How do we set up our furniture/items to make this work? We'll see it by inspecting the sample object in detail.

Right click the object to edit, then click the "Content" tab. When we do this, we're inspecting the contents of the ROOT PRIM. You should see:

• The "[Black Tulip] My Music Box - Basic Edition" script.
• The [Black Tulip] Songs Config configuration notecard
• Several sample soundclips.

What does this mean? That the script and sound clips, have to be dropped into the ROOT PRIM. This is the default when we simply right click an object, then select "Edit" from the menu.

Having this clear, now let's examine the sample object in detail. It consists of several linked prims: The music box parts, little engine pieces and a winding key. Right click to edit, click "Edit linked", and now:

• Inspect the winding key's description. It says:

spinPrim;<1.0,0.0,0.0>;1.0;1.0

What does this description mean? That's what we cover in the next section.

SETUP: HOW TO SET UP THE SPINNING PARTS

As you can check in the sample [Black Tulip] My Music Box - Sample Object object, this script allows you to ALSO rotate, by spinning, all the child prims you wish to rotate (until you hit the script's memory limit - don't worry, this won't happen with five/ten spinning prims). You could also make the root prim to rotate. Perhaps this is not what you would like anyway, but feel free to make a copy of your object and try this if you're curious about :-) (basically, it will make the whole object to spin around the root)

We have to begin by rezzing our object.
Set the rotation of the ROOT PRIM to:

X = 0.00
Y = 0.00
Z = 0.00

Don't worry if your object doesn't look like you have designed it. You will be able of rotating it again as you wish ONCE you have gathered the values for the spin vectors.

Rez the [Black Tulip] My Music Box - Sample Object sample object to follow this explanation. Pay special attention to the sections of the diagram that are highlighted.

Set its root rotation as said above:

X = 0.00
Y = 0.00
Z = 0.00

Now go into Edit linked parts. Click the winding key.

Check its description field. It says:

spinPrim;<0.0,0.0,1.0>;1.0;1.0

What does this mean?

The first that we have to know is that the script will read the semicolons (;) and take all the values between them.
So in the case above:

spinPrim;<0.0,0.0,1.0>;1.0;1.0

we see that there are FOUR pieces of information:

spinPrim
<0.0,0.0,1.0>
1.0
1.0

It is VERY IMPORTANT the order these values appear! If they don't appear in this exact order, the script won't be able to read the values of the prim we want to spin.

What each of those values mean?

First one:

spinPrim

means that the script has to consider this prim as a spinning one. The word has to be written exactly as said above. It IS case sensitive!

The second one:

<0.0,0.0,1.0>

is the spin vector. Don't worry, it is explained after this how to obtain it correctly.

The third one:

1.0

is the spin rate value. It is a number with decimals that, to make it easy to understand, we can think of as the velocity, so the smaller the value we type in, the slower the piece will spin and the reverse.

and the last one:

1.0

might be complicated to understand and, anyway, it doesn't make sense if our prims are not physical. Since this last one can be very technical, we will leave it always as 1.0. If you have the knowledge to follow the explanations from the wiki, then you can learn more about it in this wiki page: http://wiki.secondlife.com/wiki/LlTargetOmega

This last value corresponds to the gain parameter the wiki mentions there.

And how the spin vector has been obtained?

With the object having the root rotation set to <0.00 ,0.00, 0.00> (as stated above), and being in WORLD COORDINATES mode, we choose the axis we want the object rotating around.

• If the axis is X, the RED one, we write the spin vector as: <1.0, 0.0, 0.0>
• If the axis is Y, the GREEN one, we write the spin vector as: <0.0, 1.0, 0.0>
• If the axis is Z, the BLUE one, we write the spin vector as: <0.0, 0.0, 1.0>

SETUP: THE CONFIGURATION NOTECARD

The configuration notecard is named [Black Tulip] My Music Box - Songs Config and needs to be written to provide all the data we want to:

• Specify which samples compose a full song
• Specify which name we want showing up on the menu for each song
• Specify the sample duration per song
• Say if we want the script to be silent or, on the contrary, to whisper in local chat the title of the selected song

(No other mode than whisper is allowed to prevent spamming avatars around that, most likely, won't be interested in knowing about songs being played.)

This data needs to be written in a specific way, so let's examine the [Black Tulip] Songs Config notecard.

The lines beginning by:

#

are comments in the notecard.

They give important reminders, so don't delete them unless you don't need them. Comment lines won't use more script memory. Comment lines won't make your script laggier. Comment lines won't make your script work slower.

So it is OKAY if you leave them for your own reference. The comments in the notecard from your package explain all the parameters: You may want to leave those comments.

The sample notecard (not the one in the sample object) shows as:

# [Black Tulip] My Music Box - Songs Config
#
#   SaySongInChat = M
#       M can be 0 or 1
#           0 for a silent script
#           1 for the script whispering in local chat the title of the song being played
#
#   Put as many of the follow lines as songs you wish to offer - Limit: 100
#   Song = BaseName | TitleMenu | SampleDuration
#       BaseName    The base name all the samples for a same song share
#       TitleMenu       The title we want appearing in the menu to select song
#                           Max: 35 characters
#       SampleDuration  Sample duration, in seconds, for the samples of that specific song
#                               A default value of 9.5 will be provided if the value is not
#                               in the range [0.1, 9.95] (10.0 won't be accepted - for your safety)

SaySongInChat = 0

Song = BaseName | TitleMenu | SampleDuration

After all the comment lines, we find the following:

SaySongInChat = 0

This means that the script will NOT say anything when a song is played. If we wish to have the script whispering which song is going to be played once selected, we would write instead:

SaySongInChat = 1

And then the lines that would define the songs. We should write ONE line with the following format PER SONG:

Song = BaseName | TitleMenu | SampleDuration

What do BaseName, TitleMenu and SampleDuration mean here?

BaseName
This is the base name all the samples for a same song share. This will be clear with an example.

Let's suppose we have a song composed of five samples, named:

Little_Black_Rain_Cloud-0
    Little_Black_Rain_Cloud-1
    Little_Black_Rain_Cloud-2
    Little_Black_Rain_Cloud-3
    Little_Black_Rain_Cloud-4

By writing the following line in the configuration notecard:

Song = Little_Black_Rain_Cloud- | Little Black Rain Cloud | 9.5

we can see that the first part, BaseName, says:

Little_Black_Rain_Cloud-

The script will look for all the samples in your object with name beginning by Little_Black_Rain_Cloud- and will find all the samples mentioned above, so internally, it will know that the five samples above are all part of the same song.

IMPORTANT: All spaces around the specified name in the notecard will be DISCARDED. This has consequences. If your samples are, for example:

Little_Black_Rain_Cloud 0
    Little_Black_Rain_Cloud 1
    Little_Black_Rain_Cloud 2

and you specify in the notecard:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

this would make the script to look for sample names like:

Little_Black_Rain_Cloud0
    Little_Black_Rain_Cloud1
    Little_Black_Rain_Cloud2

and not like:

Little_Black_Rain_Cloud 0
    Little_Black_Rain_Cloud 1
    Little_Black_Rain_Cloud 2

Rename your samples accordingly before running into this issue. Usually, all songs you purchase will have names that won't be a problem in this regard.

TitleMenu
The title we want appearing in the menu to select song.
Max: 35 characters - Longer titles will be cut to fit this

Continuing with the sample line said above:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

we find

Little Black Rain Cloud

as value for TitleMenu, so this will be shown in the menu as the title for that song.

SampleDuration
Sample duration, in seconds, for the samples of that specific song.
A default value of 9.5 will be provided if the value is not in the range [0.1, 9.95] (10.0 won't be accepted - for your safety)

In the sample line we're using to explain this:

Song = Little_Black_Rain_Cloud | Little Black Rain Cloud | 9.5

we are saying that all the samples that are part of this song have a duration of 9.5 seconds. Since this value is in the allowed range for the script (greater or equal than 0.1 AND less or equal than 9.95), it will be accepted as the sample duration - for that one song.

WHERE DO I PURCHASE SONGS?

In order to have this item working, you will need, of course, to have songs to work with!

You can always check the Second Life Marketplace for songs. I sell some public domain, full permissions songs that you may use in items you create, at my main store.

But then, you can create yourself the samples you need and upload them. I explain all the procedure in the "Music!" book, which you can purchase in Marketplace or inworld.

This might be, perhaps, the best choice: that you look for public domain sources and you create your own samples. Be careful and do not use songs that have copyright!

SETUP: THE MAIN SCRIPT, AS A MODULE YOU CAN USE FROM ANOTHER SCRIPT

Check the following section on this page, knowing that:

[Black Tulip] ***Script Name*** [MODULE] refers to [Black Tulip] My Music Box - Basic Edition [MODULE]
CODE_NUMBER is -18640985
NAME_ON_MENU is Music

AVSitter line looks like: BUTTON Music|-18640985
MLP line looks like: LINKMSG Music | 1,-4,-18640985,fromMLP

You have example AVpos and .MENUITEMS notecards with your purchase. Remember that this works too with AVSitter 2.


If you run into any problem with this script, please give a complete description of your issue in the following online form.

I'll get back to you after I have read your report and replicated your issue inworld, according to your description of it. Please, be detailed.

-- Auryn Beorn