Support

This page is valid for VESPA 0.8.9

  1. Installation
  2. Content Management
  3. Configuration
  4. Customization
  5. Development
  1. Installation
  2. Extract all files and directories of the downloaded ZIP-file of VESPA and copy them together with your audio collection to a web directory. That's it, have fun.

  3. Content Management
    1. Audio files
    2. VESPA supports MP3 and M4A files. The files must have the file extension .mp3, .MP3, .m4a or .M4A. Otherwise the file is ignored. Simply upload your file(s) via FTP or web upload from your provider to the web space where VESPA is installed. The directory should look like this afterwards:

      [VESPA] 			(VESPA directory)
      index.php			(VESPA index.php)
      wow-an-m4a-file.m4a		(M4A File)
      your-mp3-file.mp3		(MP3 File)
      your-second-mp3-file.MP3	(MP3 File)
      

      VESPA will then try to figure out the files´ artist and title, as well as cover art and other information and will display all of them. The file name may contain spaces (tested on Linux web space). If you want to "remove" a file from the page, simply delete it on your web space.

    3. Directories
    4. VESPA detects subdirectories and will show them as menu items. The end user can navigate to these directories as if they were pages. Again you can upload audio files to these directories. After creating subdirectories your root directory could look like this, whereas 'Your Custom Folder' and 'Second_Custom_directory' are shown as navigation items:

      [Your Custom Folder]		(directory)
      [Second_Custom_directory]	(directory)
      [VESPA] 			(VESPA directory)
      index.php			(VESPA index.php)
      wow-an-m4a-file.m4a		(M4A File)
      your-mp3-file.mp3		(MP3 File)
      your-second-mp3-file.MP3	(MP3 File)
      

      If you use VESPA on Linux web space it is case sensitive which means that 'Music' and 'music' are two different directories. However, they will be sorted alpabetically, showing the directory with the small letter first. Directories may contain spaces (tested on Linux web space).

    5. Page main text
    6. If a folder contains a text file that is called index.txt VESPA will show this file as a sort of main text for this page.

      The text file may contain HTML tags. They will be interpreted by the browser. If you do not want HTML tags and would like the text file to be shown as raw text change the setting in the config.php at '$indextxt_plain' to 'true'.

      It is known that a wrong encoding of the text file may result in wrong characters in the front end. It is recommended to use UTF-8 formatted text files. If you encounter problems try to set the format to 'UTF-8 without BOM'.

    7. Text information next to the audio file
    8. Audio files may contain a lot of meta data in their id3v1 tags, id3v2 tags or ape tags. But sometimes it is useful to provide additional information which either cannot be stored in the audio file itself due to its length or you want it to contain HTML and style information. If there is a text file with exactly the same name as an audio file with the file extension .txt, it will be shown next to the player. So if there is a MP3 file called 'myaudiofile.mp3' and you upload a text file called 'myaudiofile.txt' VESPA will parse the text file.

      The text file may contain HTML tags. They will be interpreted by the browser. If you do not want HTML tags and would like the text file to be shown as raw text change the setting in the config.php at '$audiotxt_plain' to 'true'.

      It is known that a wrong encoding of the text file may result in wrong characters in the front end. It is recommended to use UTF-8 formatted text files. If you encounter problems try to set the format to 'UTF-8 without BOM'.

    9. Languages
    10. You can offer several languages for the front end. VESPA tries to detect if a requested language is available. It then searches if there are an index.txt and audio-text-files with the same primary language subtag available. That means that VESPA will show index.fr.txt and myaudiofile.fr.txt to clients that request french. See www.seoconsultants.com/meta-tags/language for the full list of tags.

      There are three different information sources for VESPA which language to use:
      1. End user request via parameter
      2. The user can request a certain language via adding the parameter and the primary language subtag as variable, e.g.: 'lang=en'.
      3. Custom setting in the config.php
      4. You can set a language that should be used if the user does not request a certain language via parameter. You can change the setting in the config.php at $defaultlanguage, e.g. $defaultlanguage = 'fr'.
      5. Auto detection by VESPA
      6. VESPA detects the browser´s language setting and tries to apply the language.

      If there are not any language files avaible, VESPA will simply try to read the standard files (e.g. index.txt, audio-file-text.txt,...).

    11. Pages
    12. The main concept of VESPA is to treat directories as menu items. However, there are several reasons why it might be useful to have PHP files that can be shown in addition to the directories (and the content they contain):

      • You have "static" content and a "static" menu that should not be rendered via directories and text files (e.g. footer menu, static navigation)
      • You want to include a certain feature and write PHP code on your own
      • You want to include content which is not located in a directory (in particular not as page main text)
      Consequently VESPA offers a way to show pages like common content management systems. These pages are located in the directory 'vespa/pages'. The php files located there are the ones that can be called via the URL parameter 'page'. So the corresponding URL for the PHP file 'foo.php' would be '?page=foo'.

    13. RSS Output
    14. By default VESPA renders an HTML page which is then sent to the client. You may alter this behaviour so that an XML that can be read by RSS readers is rendered. You can do so by adding '&rss=audio' to the current URL.

      The default theme includes an RSS Button at the top right. By clicking there the current page is reloaded as RSS output. It is the same address you would have to provide for any RSS feed reader. You can exclude this button at the very beginning of 'vespa/includes/audio.inc.php'.

      Problems with RSS output may basically occur for two reasons:

      1. Your index.txt or text file next to the audio file (see above) are encoded other than UTF-8 without BOM (e.g. ANSI). As a result the XML cannot be rendered correctly and the file ends beneath the head line. Solution: set the encoding of the text files to UTF8 without BOM.
      2. You have an index.txt or text file next to the audio file (see above) which are encoded with UTF-8 without BOM and contain HTML (especially links). When you have set '$indextxt_plain' in 'vespa/config.php' to true at the same time (which is actually a strange combination) the XML cannot be rendered correctly which results in a file that ends beneath the head line. Solution: set '$indextxt_plain' in 'vespa/config.php' to false.

  4. Customization
    1. Create your own theme
    2. Creating your own theme is rather easy with common knowledge of HTML and CSS.

      The best way to start is to copy the standard theme 'Silver' and rename it:

      • Go to 'vespa/theme' and copy the directory 'silver' and all of its files.
      • Rename it, e.g. to 'customtheme', and copy it to 'vespa/theme'.
      • Then change the setting in config.php at '$theme' to the full path of the directory, e.g. $theme = 'vespa/themes/customtheme'.

      VESPA basically only requires two files for the theme:
      • template.inc.php
      • This file is called by index.php which is located in the 'root'. template.inc.php contains the main HTML for the pages. At certain points it includes other PHP files that are located in 'vespa/includes'. They are necessary for certain features and hold HTML tags as well. If you do not need certain features simply delete the include command.
      • style.css
      • This file contains the style information. If you do not want to change the basic layout it is usually sufficient to change the style information here.

    3. Develop an own feature
    4. If you are familiar with PHP it is rather easy to extend VESPA´s features with your own. Simply write the PHP into a file that you place in 'vespa/includes' and include it at the proper position in template.inc.php. Use existing style information from style.css or add new ones. If you enhance VESPA with some features tell me about it and share it with other users.

    5. Debug mode
    6. VESPA uses a few internal variables you might want to use. You can enable a debug mode in config.php when you set '$allowdebug = true'. Add 'debug' as parameter to the URL to see the variables, e.g. 'http://yourdomain.com/music/index.php?dir=/subdirectory&debug'.

    7. Translations
    8. VESPA has only a few messages to the end user. However, they are available in several languages. If you want to engage in enhancing VESPA translate it in to a new language or improve the existing translations! The language files are located in 'vespa/languages'. Open the file with the corresponding language subtag in your editor and change the messages. If you created a new language file please send it to me and I will include it in the next version of VESPA.

  5. Development
    1. Product Backlog
      • Improving presentation of VESPA´s default theme 'Silver' on different clients (Tablets, mobile,...) by introducing responsive design techniques
      • An administration back end for convenient configuration and file handling (uploading and deleting files, creating, renaming and deleting directories, editing texts, etc.)
      • Support of playlist(s)
      • Offering embed code for end user to embed files on their own page
      • Testing on more servers would be nice (especially Windows/IIS and other Unix-like environments and web servers - however, VESPA works fine with Linux, Apache, PHP 5.2.x and PHP 5.3.x)
      • Search (long term goal)
    2. Known issues
      • Directories that contain a quote are not displayed
    3. No goals currently
      • Nice URLs
      • Full support of Windows/IIS (as long as I do not have to adjust the code for it...)
    4. Changelog
    5. If you are really interested in such things you can find the changelog in the ZIP package.