customerlogin
customerlogin
index features pricing register manual download forum bandlogin


OMS - Open Music Source   Open Music Source
  Code Package & Web Service Manual
  (Ver 1.4 / Last Changed: 1-Jan-2008)

Welcome to Open Music Source!

This document should help you with installing the OMS codes and get it running on your server to integrate our content into your website.
We, the OMS developers, thank you for choosing our software and hope you find it useful in all your endeavors.


1. Getting Started

1.1 Package content
Files inside the archive:

  • common_functions.php
  • get_artist.php
  • get_artist_article.php
  • get_artist_concerts.php
  • get_artist_list.php
  • get_artist_radio.php
  • get_artist_rating.php
  • get_artist_reviews.php
  • get_artist_songs
  • get_band_members.php
  • get_concert.php
  • get_concert_list.php
  • get_song.php
  • get_song_article.php
  • get_song_charts.php
  • get_song_list.php
    •
    • inc/4.3.10/functions.php
    • inc/4.3.10/oms_xlm_library.php
    • inc/5.1.2/functions.php
    • inc/5.1.2/oms_xlm_library.php
    • inc/config.php
    • inc/nusoap/lgpl.txt
    • inc/nusoap/nusoap.php
    • inc/nusoap/README.txt
  • is_artist_my_paying_customer.php
  • manual.html
  • send_email_to_artist

    • ...about the files and folders:

    The blue colored files represent the Web Service functions where we included code comments and example output. These codes will work right away when executed (on your server or localy with an apache installed) as they are prepared and provided with all required elements. We picked example artist- or genre IDs from our database if it was required for the function. These files are also linked from within this manual for demonstration and source code viewing.

    For the more advanced programmers we included the same Web Services functions as mininal code versions which are completely free of example values and comments.

    The folder 'inc' contains required files which need to be included to execute the OMS Web Services. The folder '4.3.10' and '5.1.2' contain PHP version specific files, so the OMS Web Services will run on servers where PHP4 or PHP5 is installed. Which of those folders is used depends on the PHP version installed on your system/server and is decided automatically by the PHP version check function in the file config.php.
    The file inc/config.php must be included in each file where you use the OMS Web Services as it contains your login and password to the Open Music Source database. If you haven't modified this file yet it will contain the login and password to the demo database and no domain information. You will need to modify this file as described in your OMS Registration E-Mail.

    # Go back to top



    1.2 Installation
    1. Register your platform/label account
    2. Download the code package and extract to a folder on your harddrive
    3. Open the file /inc/config.php with a code-/text editor of your choice
    4. Modify the file by inserting: your login, your password and your domain name (see also the E-Mail you got from us after registration)
    5. Upload the complete folder to your server, preserving the given folder structure
    When you've done everything correctly you should be able execute the functions. Test it, for example open the file get_artist.php on your server and see if you get data back from the OMS database. If you're having problems you should first of all use the debug function.

    # Go back to top



    1.3 Understanding the basics
    First of all you should have a look at a more simple function to understand the basics of executing a OMS Web Service. Please open the source code of get_artist.php. Note that we are using a "blue colored" file from the code package (see above for the meaning of colors).

    Let's have a look at the complete source code, step by step (make sure to read the inserted comment boxes carefully).

    <?

    /************************************************************************
    *
    *                  OMS Web Service Functions 1.3
    *                  -----------------------------
    *
    *     Copyright:   (C) 2006 moving primates GmbH
    *      Function:   GetArtist
    *   Description:   Gets the basic artist data of one artist.
    *   Change Date:   28/Feb/2006
    *
    *************************************************************************

    ↑ The first lines of the PHP document telling some description about the function. You will find in every example document.

    *   REQUIRED ELEMENTS:
    *
    *   The following elements must be send with the request:
    *
    *   - ArtistID
    *   - Fieldlist

    ↑ Tells you about the required elements of the Web Service. Note that at least one required element applies for every Web Service function, here it's two of them: ArtistID and Fieldlist.

    ArtistID: As get_artist is a function which gets the data from one specific artist, it is required to set from which artist to get the data. This is done with the required element ArtistID as all artists (as well as songs, reviews, et cetera) are assigned to one unique identifier.

    Fieldlist: Fieldlist makes it possible to request your own selection of elements from the Web Services. For example you would like to request ArtistName and ArtistGenreName but you do not need PostalCode, City or CountryName, so you can leave it out of the request. The Fieldlist must contain at least one Field Element as a child element.

    You will find more information about the elements (in fact there is a third) later on in this manual.

    *   FIELD ELEMENTES:
    *   
    *   The following are Field elements which define what you get back from
    *   the Web Service function. They must be named "Field", their value
    *   must be the exact name of the following enumeration and they must be
    *   created as a child element of "Fieldlist".
    *
    *   Field elements are optional, however it is required that you
    *   create at least one; their send order is irrelevant.
    *
    *   - ArtistName
    *   - ArtistURL
    *   - Website
    *   - MusicalInfluence
    *   - SoundsLike
    *   - ArtistPictureExists
    *   - FirstOnlineDate
    *   - PostalCode
    *   - City
    *   - CountryID
    *   - CountryCode
    *   - CountryName
    *   - ArtistGenreID
    *   - ArtistGenreParentID
    *   - ArtistGenreTopParentID
    *   - ArtistGenreName
    *   - ArtistParentGenreName
    *   - ArtistTopParentGenreName

    ↑ The list of Field Elements which can be requested for this OMS Web Service. You will find this list inside the function's comments whenever Fieldlist is part of the list of required elements which is not always the case as some Web Services just get you a small ammount of data for which it would not make sense to use Field Elements.

    Enough with the comments now, let's get to the action!

    $ArtistID = "42028"; // Example ID from an artist

    ↑ As previously mentioned, ArtistID is a required element for this Web Service function, therefore we declare this example ID.

    include("inc/config.php"); // Example path, point it to your config.php

    ↑ Including the file config.php using the default path, look under package content for details of that file.

    $dom = create_document();
    $root = create_root_element($dom, "OMS");
    create_element_attribute($root, "xmlns", $oms_cfg['artist_data_xmlns'] . "/GetArtist");

    ↑ Defines the path to the XSD files for the Web Services. In our example codes (and the minimal code) we already inserted the correct path so don't change anything here.

    The XSDs are available at http://xmlns.openmusicsource.net/1.3 You might find them useful when you advance working with the OMS codes as you can see many things at a glance.

    // Here we are defining the FIELDLIST elements (requesting all available)

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistName");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistURL");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "Website");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "MusicalInfluence");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "SoundsLike");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistPictureExists");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "FirstOnlineDate");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "PostalCode");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "City");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "CountryID");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "CountryCode");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "CountryName");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistGenreID");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistGenreParentID");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistGenreTopParentID");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistGenreName");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistParentGenreName");
    add_child_element($el_fields_list, $el_field);

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "ArtistTopParentGenreName");
    add_child_element($el_fields_list, $el_field);

    ↑ Definition of the Field elements for Fieldlist. In all of our example codes files we request all available Field elements.

    Which fields are going to be requested depends on your descision of what would make sense on your website. If you don't need a Field element you can simply leave it out by deleting the (3) lines of code.

    For example you don't need the country name of the artist, so delete the lines:

    $el_field = create_element($dom, "Field");
    set_element_value($dom, $el_field, "CountryName");
    add_child_element($el_fields_list, $el_field);

    The procedure for each element is always the same: the first line creates an element, the second line declares its value and the third line adds it to the Fieldlist as a child element.

    // Preparing the XML which is going to be send

    add_child_element($root, $el_artist_id);
    add_child_element($root, $el_fields_list);

    $xml_str = dump_to_string($dom);

    $par = array("String_1" => $oms_cfg['ws_login'],
                    "String_2" => $oms_cfg['ws_password'],
                    "String_3" => $xml_str );

    ↑ Before calling the Web Service function GetArtist we need to put all created elements together with your login and password into an array ($par).

    // Executing the Web Service function "GetArtist"

    $GetArtist = ProcessWSCall($oms_cfg['artist_data_ws_url'], "GetArtist", $par, $oms_cfg['artist_data_xmlns']);

    ↑ Here we execute the Web Service function GetArtist and put the array we get back into $GetArtist. We now have the data we requested and can read it out the way we want on our website. Have a look in the example codes, we created the code for variable assignment and output there already.


    Finally let's have a look on the structure of the code. ↓

    # Go back to top



    1.4 The three elements: Required, Field, Filter
    Beside the required elements (ArtistID and Fieldlist) and the field elements (ArtistName, Website, et cetera), there is another type of element which hasn't been covered in 1.3. It called filter element and you will find it in functions where there's a lot of data coming back and sorting/filtering makes sense. See GetArtistList for example - this function searches the complete OMS artist catalogue. You can use various filter elements to limit the output by genres, postal codes, countries and so on.

    So again, envision the following: If you understand these basics from 1.3 and 1.4 you should be able to work with all the other Web Services as well, the technique remains the same. How you output the data and design the webpages arround it is completely up to you.

    # Go back to top



    2. The Web Service Functions

    2.1.1 GetArtist
    Execute this function | View the source code

    This function gets the basic information about one artist at a time. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:
    These are the available field elements for this function:

    # Go back to top



    2.1.2 GetArtistArticle
    Execute this function | View the source code

    Gets the artist description, history, press news and additional info texts of one artist. It's possible to request the artist info in different languages if those are available.


    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.1.3 GetArtistConcerts
    Execute this function | View the source code

    This function gets all concert dates of one artist and its related concert information. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.1.4 GetArtistList
    Execute this function | View the source code

    This function gets the basic information about all OMS artists which are online and included inside your artist pool. You can set various filter for this function to filter and limit the output.


    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.1.5 GetArtistRadio
    Execute this function | View the source code

    This function will tell you if a lofi-/hifi-stream of MP3s from an artist is available. The artist account must be online and exist in your artist pool for this function to get any data.


    This is the only required elements for this function:

    # Go back to top



    2.1.6 GetArtistRating
    Execute this function | View the source code

    This function gets the rating score which has been stored for this artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    # Go back to top



    2.1.7 GetArtistReviews
    Execute this function | View the source code

    This function gets all reviews and related information of one artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.1.8 GetArtistSongs
    Execute this function | View the source code

    Gets the data of all uploaded songs of one artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.1.9 GetBandMembers
    Execute this function | View the source code

    Gets the data of all entered bandmembers of one artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.2.1 GetConcert
    Execute this function | View the source code

    This function gets the data from one concert date entry and the basic info of the related artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.2.2 GetConcertList
    Execute this function | View the source code


    This function gets the data from all concerts available in the OMS database. Additionally it gets the basic data from the related artist. The artist account must be online and exist in your artist pool for this function to get any data.

    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.2.3 GetSong
    Execute this function | View the source code


    Gets the data of one specific song. The artist account which is related to the song must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    These are the available field elements for this function:

    # Go back to top



    2.2.4 GetSongArticle
    Execute this function | View the source code

    Gets the song description text of one song. It's possible to request the text in different languages if those are available.


    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.2.5 GetSongCharts
    Execute this function | View the source code

    This function will get a song chart list which is ordered by plays or downloads based on your platform. Additionally it will get the basic data about the related artists. You can use a filter to show genre specific charts.


    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.2.6 GetSongList
    Execute this function | View the source code

    This function gets the data of all songs of the OMS database which are online and which related artists are online and included inside your artist pool. You can set various filter for this function to filter and limit the output.


    These are the required elements for this function:

    These are the available field elements for this function:

    These are the available filter elements for this function:

    # Go back to top



    2.2.7 IsArtistMyPayingCustomer
    Execute this function | View the source code

    Checks if the artist has an active paid service running on your platform. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    # Go back to top



    2.2.8 SendEmailToArtist
    Execute this function | View the source code

    Sends an e-mail to one artist. The artist account must be online and exist in your artist pool for this function to get any data.


    These are the required elements for this function:

    # Go back to top



    2.2.9 GetArtistIDByURL
    Execute this function | View the source code

    Gets back the ID of an artist by sending in the Artist URL. This function makes sense if you would like to build short URLs like http://www.yourdomain.com/Artistname and automatically refer visitors to the artistpage.


    These are the required elements for this function:

    # Go back to top



    3. Common PHP and Web Service Functions
    These are simple functions which you will probably use quite frequently on your website. Part of them are just pure PHP code, some have OMS Web Services built in. For a demonstration of these functions visit click here or open the file common_functions.php which you will find inside the code package you can download from our website here.



    4. Javascript Functions

    4.1 Including the OMS-Javascript
    In order to display music-links for the visitors of your website to play and download songs, you will first of all need to include and modify the following javascript on your website. This javascript needs to be included on everypage where you want to display stream- or download-links.

    Add the following script and your partner ID:

    <script type="text/javascript" language="JavaScript" src="http://mp3.openmusicsource.net/stream/1.1/js_stream_link.php?oms_partner_id=PARTNER_ID"></script>

    Modify the code by replacing PARTNER_ID with your actual partner ID.
    If you don't know your partner ID you can look it up by loging into your administration area here.

    # Go back to top



    4.2 Stream-, Download- and Buy-Links
    The field elements LoFiLink, HiFiLink and DownloadLink contain the code which define the link. You will get those field elements from various OMS Web Services (such as GetSong). Take this code and put it on your page as javascript (you need to add the surrounding script tags) wherever you want the links to appear. (In case the song you display is a paid download, the field element DownloadLink will return a buy-link.)

    The code you put on your page should look like so (song ID is imaginery):
    <script type="text/javascript" language="JavaScript">
        show_download_link(123456);
    </script>
    Furthermore, you should define the looks of your links. You can place the following configuration in your general page header and/or define each link individually.


    Add the following code to configure the look of your lofi-, hifi- and download links:
    <script type="text/javascript" language="JavaScript">

        // LOW QUALITY LINKS

        _oms_lofi_txt = 'LINKNAME';
        _oms_lofi_opts['OPTION'] = 'SETTING';               // remove this line if you don't use options
        _oms_lofi_opts['OPTION'] = 'SETTING';               // on the other hand add as many as you need


        // HIGH QUALITY LINKS

        _oms_hifi_txt = 'LINKNAME';
        _oms_hifi_opts['OPTION'] = 'SETTING';               // remove this line if you don't use it


        // DOWNLOAD LINKS

        _oms_download_txt = 'LINKNAME';
        _oms_download_opts['OPTION'] = 'SETTING';   // remove this line if you don't use options

    </script>
    Modify it as follows: Add the following code to configure the look of your the buy-links for payable downloads:
    <script type="text/javascript" language="JavaScript">

        // BUY LINKS

        _oms_buy_price_position = 'PRICE_POSITION';
        _oms_buy_price_opts['OPTION'] = 'SETTING';     // remove this line if you don't use options

        _oms_buy_txt = 'TXT_NAME';
        _oms_buy_txt_type = 'TXT_TYPE';
        _oms_buy_txt_opts['OPTION'] = 'SETTING';        // remove this line if you don't use options

    </script>

    # Go back to top



    4.3 Playlist-Streams for Artists
    This is how you can display a playlist-stream of all tracks of one artist.

    The code you put on your page should look like so (song ID is imaginery):
    <script type="text/javascript" language="JavaScript">

        opts = new Array();                          // you can delete these lines...
        opts['OPTION'] = 'SETTING';         // if you don't use any options, or also...
        opts['OPTION'] = 'SETTING';         // add as many options you need.

        show_play_all_link(ARTIST_ID, 'LINKTYPE', 'LINKNAME', opts);

    </script>

    # Go back to top



    4.4 Playlist-Streams for Chart-Ranges
    This functions displays a playlist-stream (lofi or hifi) for a selected chartrange of your choice (e.g. display a hifi-stream for the current top 10 downloaded songs of your rock chart).

    Note you need to include the OMS Javascript for this purpose.

    Include this javascript code:
    <script type="text/javascript" language="JavaScript">

        opts = new Array();                          // you can delete these lines...
        opts['OPTION'] = 'SETTING';         // if you don't use any options, or also...
        opts['OPTION'] = 'SETTING';         // add as many options you need.

        show_chart_link(GENRE_ID, 'CHARTTYPE', 'QUALITY', 'START', 'END', 'LINKNAME', opts);

    </script>
    Modify it as follows:

    # Go back to top



    4.5 Displaying Pictures
    At the moment there are two different kind of images which can be read out from the OMS database: artist and song pictures. We offer a tool which lets you resize these pictures on the fly. Modify the following URL to fit your needs and use it as the source attribute of an image tag.

    http://pics.openmusicsource.net/cgi-bin/get_pic.cgi?type=__&id=__&max_size=__&max_width=__&max_height=__

    You will need to replace the blank spaces (underscores) beside the variables:

    Let's say we have an artist picture of 295 x 295 pixels in size and would like to display it with 150 x 150, 100 x 100 and 50 x 50 pixels, then we would use this code as our image's source:

    http://pics.openmusicsource.net/cgi-bin/get_pic.cgi?type=artist&id=35748&max_size=max_ratio&max_width=150&max_height=150

    http://pics.openmusicsource.net/cgi-bin/get_pic.cgi?type=artist&id=35748&max_size=max_ratio&max_width=100&max_height=100

    http://pics.openmusicsource.net/cgi-bin/get_pic.cgi?type=artist&id=35748&max_size=max_ratio&max_width=50&max_height=50


    Resize 150 x 150Resize 100 x 100Resize 50 x 50

    # Go back to top



    5. Appendix

    5.2 Country List
    Here you have the list of countries which are existing inside the OMS network.

    Country ID     Country Code     Country Name
    3 AF Afghanistan
    4 AL Albania
    5 DZ Algeria
    6 AS American Samoa
    7 AD Andorra
    8 AO Angola
    9 AI Anguilla
    10 AQ Antarctica
    11 AG Antigua and Barbuda
    12 AR Argentina
    13 AM Armenia
    14 AW Aruba
    1 AU Australia
    2 AT Austria
    15 AZ Azerbaijan
    16 BS Bahamas
    17 BH Bahrain
    18 BD Bangladesch
    19 BB Barbados
    24 BY Belarus
    20 BE Belgium
    21 BZ Belize
    22 BJ Benin
    23 BM Bermudas
    25 BT Bhutan
    26 BO Bolivia
    27 BA Bosnia-Herzegowina
    28 BW Botswana
    29 BV Bouvet Island
    30 BR Brazil
    31 BN Brunei
    32 BG Bulgaria
    33 BF Burkina Faso
    34 BI Burundi
    42 KH Cambodia
    43 CM Cameroon
    35 CA Canada
    44 CV Cape Verde
    41 KY Cayman Islands
    38 CF Central African Republic
    36 CL Chile
    39 CN China
    48 CX Christmas Island
    53 CC Cocos Islands
    46 CO Colombia
    47 KM Comoros
    49 CG Congo
    40 CK Cook Islands
    45 CR Costa Rica
    37 CI Cote d-Ivoire
    50 HR Croatia
    52 CY Cyprus
    51 CZ Czech Republic
    54 DK Denmark
    55 DC District of Columbia
    56 DM Dominica
    57 DO Dominican Republic
    58 DJ Dschibuti
    64 TP East-Timor
    59 EC Ecuador
    60 EG Egypt
    63 SV El Salvador
    61 GQ Equatorial Guinea
    65 ER Eritrea
    66 EE Estonia
    62 GQ Ethiopia
    68 FK Falkland Islands
    67 FO Faroe Islands
    69 FJ Fidschi
    70 FI Finland
    71 FR France
    72 GF French Guiana
    73 PF French Polynesia
    74 GA Gabun
    76<