1. Introduction

TubePress is a PHP library that displays beautiful YouTube video galleries in your web site. It's highly configurable and easy to use. Check out a demo gallery here.

There are two different TubePress packages available:

  1. A WordPress plugin (free!)
  2. TubePress Pro - A stand-alone library for use anywhere that supports PHP (only $10)

Both packages are released under the GPLv3. TubePress was created, is developed and maintained by Eric D. Hough

2. Download

2.1 Latest stable release

The latest packages of TubePress can always be downloaded as zip files from http://tubepress.org/download

2.2 Subversion

Interested in using the very latest version of TubePress? You can use any Subversion client to check out the latest developmental build of the WordPress plugin.

2.2.1 From the command line

If you have command line access to your server, and have an svn client in your path, this method is the easiest.
  1. Change directories to wp-content/plugins
  2. Make sure you've removed any existing installs of TubePress from this directory
  3. Execute
    svn checkout http://tubepress.googlecode.com/svn/trunk/ tubepress
That's it! You'll now be using the very latest build of the plugin. You can now upgrade at any time like this:
  1. Change directories to wp-content/plugins/tubepress
  2. Execute
    svn update

2.2.2 Using FTP

You'll need to check out the latest build locally (i.e. to your desktop machine) and then upload it to your server using FTP.
  1. Use any SVN client to browse to http://tubepress.googlecode.com/svn/trunk/
  2. Checkout the trunk directory to a local directory called tubepress
  3. Upload the tubepress directory you just created to your WordPress installation at wp-content/plugins

2.3 Nightly Builds

You can download a nightly build of the WordPress plugin package from http://tubepress.org/builds/tubepress_nightly.zip

3. WordPress Plugin

As a WordPress plugin, TubePress lets you easily insert custom video galleries throughout your WordPress-powered blog.

3.1 Quick Start

TubePress can be installed and activated just like any other WordPress plugin. See the WordPress docs on plugin management for more information.

  1. Download the plugin from http://tubepress.org/download
  2. Unzip into your plugins directory (wp-content/plugins)
  3. Activate TubePress from Site Admin > Plugins
  4. Configure from Site Admin > Settings > TubePress
  5. Type
    in a post or a page where you'd like to insert your gallery (this is actually the simplest form of a TubePress shortcode). See the image below for an example.
Inserting a gallery into a WordPress post

This will result in something like the following…

3.2 Multiple galleries

The options in Settings > TubePress are the global options for TubePress. The real power of the plugin lies in the ability to put multiple galleries on multiple pages. You can do this by using TubePress shortcodes on your posts/pages.

For example, say on one page I want to display a gallery of videos that are tagged with "football". On this page, I would type

[tubepress mode='tag', tagValue='football']

on the page where I want the gallery to show up. And say on another page I want to display a gallery with the default (global) options that were set in Settings > TubePress. On this page I would type


where I wanted the gallery to show up. You can follow this procedure for unlimited galleries on unlimited posts/pages. Just use any TubePress shortcode to control the gallery content. Get creative!

3.3 Upgrading

Upgrading is usually just a matter of copying the latest version of TubePress over your existing installation. However, if you want to be sure there are no problems, follow these directions in order.

  1. Remove your existing TubePress install directory (wp-content/plugins/tubepress)
  2. Unzip the latest version of TubePress into (wp-content/plugins)
  3. Visit Site Admin > Settings > TubePress once initialize your options

3.4 Sidebar Widget

The TubePress plugin comes with widget functionality, which allows you to place a customizable list of videos in your blog's sidebar. Here's an example of the widget's output:

There are no separate installation instructions; if you've installed and enabled the TubePress plugin then you're done. Please see the WordPress widget documentation for general info on how to enable and disable widgets.

This is what the TubePress widget control looks like:

In the "Title" section of the widget control, enter the text you'd like for the sidebar's header.

To customize which videos show up in your sidebar, just use a TubePress shortcode. Please note that by default, the TubePress widget will use the following shortcode:

[tubepress resultsPerPage='3', views='false', description='true', descriptionLimit='50', playerLocation='popup', thumbHeight='105', thumbWidth='135']

Of course, like any TubePress shortcode, you can override any setting you like.

3.5 Initialize your options

If you'd like to reset your TubePress options to their default values, you can do so by using a special page nested inside the plugin. If your blog URL is
you'd need to navigate to
with your web browser. Once there, you can just click the Reset TubePress Options button. Of course, you'll need to be a WordPress administrator (access level 9) for your blog to do this.

4. TubePress Pro

TubePress Pro allows you to run TubePress anywhere that supports PHP5. This means that you can easily insert video galleries in your PHP-enabled site! A very basic understanding of PHP programming is helpful.

4.1 Plain PHP

Here are step-by-step instructions for using TubePress Pro on your site.
  1. Download
    After you purchase TubePress Pro, check your email that you've registered with PayPal. You'll find an email, from tubepress.org, that contains your download link. When you click on this link, your web browser will prompt you to download (or open) a zip file containing TubePress Pro. Click "Save file" and download the zip file to somewhere easy to find, like your desktop. As of this writing, the name of the zip file is tubepress_pro_1_7_0.zip.

  2. Unzip
    Unzip the file you just downloaded (tubepress_pro_1_7_0.zip). It will expand into a directory named tubepress_pro_1_7_0.

  3. Upload
    This entire directory that you unzipped must be uploaded to your web server in a place that's web accessible. In this example, my webserver has a URL of http://myblog.com and a document root of /var/www/html, so I'll need to upload the entire tubepress_pro_1_7_0 directory to anywhere inside /var/www/html on myblog.com. For this example, I'll just upload the directory to the /var/www/html directory.

    Now my TubePress installation is web accessible at http://myblog.com/tubepress_pro_1_7_0 and on the server's filesystem at /var/www/html/tubepress_pro_1_7_0.

  4. Verify upload
    It's a good idea to make sure that the directory you just uploaded is actually readable by your web server. Try navigating to http://myblog.com/tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php. You should get a blank white screen with no errors.

  5. Create gallery page
    I want to create a gallery in /var/www/html/index.php. Below are the contents of index.php. It's an extremely simple PHP file with four steps added to include a TubePress gallery. We'll go the steps one-by-one.
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    /* STEP 1: Enter the web-accessible URL of your TubePress installation */
    $tubepress_base_url = "http://myblog.com/tubepress_pro_1_7_0";
    /* STEP 2: Include the TubePress stand-alone library file (tubepress-standalone.php) */
    require_once "tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php";
    <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
                    <title>TubePress Standalone Example</title>
                    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
                    <!-- STEP 3: Include this statement inside the HEAD of your HTML document -->
                    <?php print tubepressHeadElements(); ?>
                    <div style="width:500px">
                            <!-- STEP 4: Call "tubepressGallery" anywhere you like -->
                            <?php print tubepressGallery("resultsPerPage='3'"); ?>
    Step 1:
    Set the tubepress_base_url variable to the web URL of your TubePress Pro installation. In this example, it's http://myblog.com/tubepress_pro_1_7_0.

    Step 2:
    Include the TubePress Pro library file, tubepress-standalone.php. This file is located right inside your TubePress Pro installation directory, so in this example it's found at tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php

    Step 3:
    In the head of your PHP file, execute print tubepressHeadElements(); one time. This will include TubePress's CSS and JavaScript files.

    Step 4:
    Anywhere you want a gallery, just execute print tubepressGallery("resultsPerPage='3'"); Note that you can put any TubePress shortcode syntax as a parameter to this function call. Note that you can leave out the opening and closing brackets of the shortcode (along with the "tubepress" word) if you like.

  6. Result
    Here's the resulting output of the example: http://tubepress.org/pro_demo

4.2 Outside the WordPress loop

You can also use TubePress Pro to insert video galleries outside the WordPress loop (outside the content of a post or page). It's even easier to use than in standalone PHP. There are just two steps, which are in bold in the code snippet below. This example shows how you can use TubePress Pro in a regular WordPress template. The steps are
  1. Include the tubepress-standalone.php file to load up the TubePress Pro libraries
  2. Anywhere you'd like a video gallery, type
    print tubepressGallery("resultsPerPage='3'");
    As the argument to this function, you can include any shortcode you'd like (with or without the square brackets).

        require_once "tubepress/env/standalone/tubepress-standalone.php";


        print tubepressGallery("resultsPerPage='3'");
        if (have_posts()) :
           while (have_posts()) :

5. TubePress Shortcodes

TubePress shortcodes are small snippets of text that allow you to easily control the content, style, and behavior of TubePress galleries. There are very similar to WordPress shortcodes, with some minor syntax differences.

TubePress will replace any TubePress shortcodes with a video gallery. Each gallery can be configured completely independently from the others, based on the content of the shortcode.

The simplest shortcode is

TubePress will replace this shortcode with a video gallery with the default settings. You can override each TubePress setting by providing shortcode attributes, which are comma-separated name-value pairs that you insert between the square brackets. They all follow the pattern
Please note the single quotes around the value!

So for instance, say I wanted a gallery with

My shortcode for this gallery would be:
[tubepress mode='favorites', favoritesValue='3hough', resultsPerPage='10', description='true', playerLocation='lightwindow']

5.1 Gallery Options

These settings control which group of videos the gallery will display.

Setting Description Valid Values Example
mode Which set of videos will be displayed favorites
[tubepress mode='featured']

5.1.1 Gallery Descriptions

Mode name Description
favorites "Favorite" videos of the given YouTube user. Accompany this mode setting with a favoritesValue attribute to define the YouTube user name. For instance
[tubepress mode='favorites', favoritesValue='3hough']
. YouTube limits the number of videos in this type of gallery to 50.
recently_featured The lastest "featured" videos on YouTube's homepage
most_discussed The most-commented videos on YouTube
most_linked Videos with the most links
most_recent Videos recently uploaded to YouTube
most_responded Videos with the most video responses
playlist Videos from the given playlist. Accompany this mode setting with a playlistValue attribute to define which YouTube playlist to retrieve. For instance
[tubepress mode='playlist', playlistValue='6813408AE8D50E6F']
. YouTube limits the number of videos in a playlist to 200. Only public playlists can be shown with TubePress.
mobile Videos suitable for mobile devices
tag Show videos matching a search term. Accompany this mode setting with a tagValue attribute to define your search term. For instance
[tubepress mode='tag', tagValue='barack obama john mccain']
user Videos uploaded by a specific user. Accompany this mode setting with a userValue attribute to define the YouTube user name. For instance
[tubepress mode='user', userValue='3hough']

5.2 Video Display Options

These settings control the overall viewing experience for the user

Setting Description Valid Values Example
playerLocation How the user will view each video. See secion 5.2.1 for descriptions of these values. normal
[tubepress playerLocation='shadowbox']
orderBy The sort order of the video thumbnails published
[tubepress orderBy='viewCount']
resultsPerPage How many video thumbnails to display on a single page Any integer x such that 0 < x <= 50 [tubepress resultsPerPage='30']
thumbHeight Vertical size (in px) of thumbnails Any integer x such that 0 < x <= 90 [tubepress thumbHeight='45']
thumbWidth Horizontal size (in px) of thumbnails Any integer x such that 0 < x <= 120 [tubepress thumbWidth='60']

5.2.1 Video Players

Player name Description
normal Plays videos in an embedded Flash player above the video thumbnails. If you'd like the page to load with a specific video at the top of the gallery, just add the video's ID to the address of you gallery as the tubepress_video argument. For instance, if my gallery has a URL of http://mygallery.com, I would use http://mygallery.com?tubepress_video=CNo7Hm0IOag to start the gallery with the video with ID CNo7Hm0IOag in the embedded player. You can use any YouTube video ID you like for this argument.
popup Plays videos in an HTML popup window
youtube Sends user to the video's original YouTube page to view the video

5.2.2 Video sort order

orderBy value Description
published Show videos in the order they were published to YouTube, with the more-recent videos first.
viewCount Shows videos in order of how many times they've been viewed, with the more-viewed videos first.
rating Shows videos in order of their rating, with the higher-rated videos first.
relevance Shows videos in order of relevance. This sort order really only applies to "tag" mode galleries

Please note that these galleries can't be sorted

5.3 Embedded Player Options

These settings apply to the embedded Flash player from YouTube

Setting Description Valid Values Example
autoPlay Toggles start of video playback without user intervention true
[tubepress autoPlay='true']
border Toggles frame around embedded player true
[tubepress border='true']
embeddedHeight Vertical size (in px) of embedded player Any positive integer [tubepress embeddedHeight='true']
embeddedWidth Horizontal size (in px) of embedded player Any positive integer [tubepress embeddedWidth='true']
genie Toggles display of "genie" menu during video playback true
[tubepress genie='true']
loop Toggles repeat of videos without user intervention true
[tubepress loop='true']
playerColor Primary and secondary colors of embedded player Two HTML color values in hex, combined with a single forward slash [tubepress playerColor='0xffaabb/0xaa2233']
quality Quality of video and audio normal
[tubepress quality='higher']
showRelated Toggles display of related videos after playback true
[tubepress showRelated='true']

5.4 Video Meta Display

These settings control what information gets printed out below each video thumbnail

Setting Description Valid Values Example
author Toggles display of video author below thumbnails true
[tubepress author='true']
category Toggles display of video category below thumbnails true
[tubepress category='false']
description Toggles display of video description below thumbnails true
[tubepress description='false']
id Toggles display of video ID below thumbnails true
[tubepress id='true']
length Toggles display of video run time below thumbnails true
[tubepress length='false']
rating Toggles display of average video rating below thumbnails true
[tubepress rating='true']
ratings Toggles display of video rating count below thumbnails true
[tubepress ratings='true']
tags Toggles display of video tags below thumbnails true
[tubepress tags='false']
title Toggles display of video title below thumbnails true
[tubepress title='true']
uploaded Toggles display of video upload time below thumbnails true
[tubepress uploaded='false']
url Toggles display of video URL on YouTube? below thumbnails true
[tubepress url='false']
views Toggles display of video view count below thumbnails true
[tubepress views='true']

5.5 Advanced Options

Various features that casual users will not likely need/want to adjust

Setting Description Valid Values Example
dateFormat Formatting of date information for videos. See http://us.php.net/date for examples Any valid string as defined by http://php.net/date [tubepress dateFormat='l jS \of F Y h:i:s A']
debugging_enabled Toggles ability to perform remote debugging true
[tubepress debugging_enabled='false']
randomize_thumbnails Toggles random thumbnail selection for each video (each video comes with several thumbnails) true
[tubepress randomize_thumbnails='false']
filter_racy Toggles filtering of "racy" videos true
[tubepress filter_racy='true']

6. Troubleshooting

6.1 Enable debug mode

This mode will print out tons of debugging information. To use it, you just need to add tubepress_debug=true to the URL string (in your browser's address bar). For instance, if the TubePress page you're trying to debug has an address of

then you should add tubepress_debug=true to the URL to enable debugging
You should see the debugging information displayed above any galleries you have. The following image shows generally what you can expect to see

6.2 YouTube Connection Test

Some web servers place restrictions on what PHP scripts are allowed to execute. TubePress needs the ability to open network connections to remote servers. One way to verify that TubePress has this ability is to run the YouTube connection test. You can find a link to the test in the debug output (see section 6.1). The test will attempt to retrieve the HTML content of YouTube's homepage, and then it will execute a sample video query against YouTube's API. The result of the latter will be printed to the screen as plain XML.

6.2 Discussion Forum

Still can't solve your issue? Try searching or posting in the TubePress discussion forum, hosted by Google Groups. You'll need a Google account to post.

6.3 Open a trouble ticket

If you can't find a solution to your problem in the discussion forum, someone may have already submitted a trouble ticket. The current list of tickets can be found at http://code.google.com/p/tubepress/issues/list. Please feel free to submit a trouble ticket. Note that you'll need a Google account.

7. Contributing

7.1 Submit a patch

Patches are always welcome! You'll receive full credit for your contribution, of course. Here's how to submit
  1. Checkout the trunk version of TubePress (see section 2.2)
  2. Generate your patch against it
  3. Submit your patch as an attachment to a new issue report at http://code.google.com/p/tubepress/issues/list

7.2 I18N

As of version 1.6.5, TubePress can be translated into any language using the gettext framework. To submit a translation...

  1. Translate the words/phrases in this file from English to your native language
  2. Attach the translated file as an attachment to a new issue. Please be sure to note your two-digit country code and your two-digit language code.

You will, of course, receive full credit for your contribution to an open source project! If you're interested in the gory details of how it works, I highly recommend reading WordPress's excellent i18n documentation.

7.3 Donate

TubePress is an open source project. I've spent many long nights working on this project. If you enjoy the software, please consider a donation. No amount is too small. Thanks!