Vixy YouTube Embed Documentation
Contents
Quick Start
Add Video Download Links
Shortcode Parameters
Alternative Shortcodes
Function Calls
Widgets
Templates
Profiles
Playlists
Custom Playlists
Transcripts
Automatically Generated Playlists
Migrating from Other Plug-ins
Thumbnails
Showing the Video Name
Using Shortened URLs
Caching
Further Embedding Options
Metadata
EmbedPlus Support
The Chromeless Player
Make Money from Vixy YouTube Embed
Licence
Quick Start
Once you've installed Vixy YouTube Embed, just enter a shortcode like this to embed a video (and optionally offer download and MP3 conversion links):
[youtube]adVEYkQIxCg[/youtube]
In between [youtube] and [/youtube] is the YouTube video ID. To get the video ID, just go to YouTube.com and play your video, then note the v= value from the URL of the page. In the above example, we're embedding the video from here:
http://www.youtube.com/watch?v=adVEYkQIxCg
So the video ID is adVEYkQIxCg.
Add Video Download Links
After installing Vixy YouTube Embed, you'll want to enable download links so your web site visitors can save videos or convert to MP3s easily. Here's how to set it up:
1. Go to Profiles, under the YouTube menu in the sidebar.
2. Make sure Show Download Links is checked:
As a bonus to you, one of the links can be an affiliate link for more powerful Jaksta video downloading and conversion products, which can earn you extra money.
Manually Adding Download Links
If you'd prefer to do this manually then the function call is named get_video_download and has one parameter - the video ID. It will return the download link URL. Example:
<a href="<?php echo get_video_download( 'Z_sCoHGIpU0' ); ?>">Download the video</a>
Alternatively, you can use the shortcode download_video. The text or image for the link is specified between the open and close shortcode tags and has three parameters:
id - The ID of the video or playlist. This is required.
target - The target of the link (e.g. `_blank`). This is optional.
nofollow - yes or no, use this to specify whether a nofollow tag should be added to the link. This is optional and by default it will be included.
Example:
[download_video id="Z_sCoHGIpU0" target="_blank" nofollow="no"]Download the video[/download_video]
Shortcode Parameters
You can modify how the video appears by adding parameters to the shortcode. For example, you can make the video appear in a 300x200 window by adding width and height parameters like this:
[youtube width=300 height=200]adVEYkQIxCg[/youtube]
Which options are available depends upon the embedding type you're using - you can specify any of them, but depending on the type, they may be ignored. There are 3 types - OBJECT, IFRAME and EmbedPlus. IFRAME is the current YouTube default and will use HTML 5, if available - this makes it ideal for maximum compatibility. However, HTML5 has a number of features that are not available with the standard Flash player.
The following parameters work with all embed types:
The following parameters with everything except EmbedPlus:
| parameter | option | description |
| autohide | 0 | The video progress bar and the video player controls will be visible throughout the video. |
| 1 | The video progress bar and the player controls will slide out of view a couple of seconds after the video starts playing. They will only reappear if the user moves her mouse over the video player or presses a key on her keyboard. |
|
| 2 | The video progress bar fades out while the player controls (play button, volume control, etc.) remain visible. (default) | |
| color | white | Make the progress bar white (see the FAQ about having a white progress bar with the light theme) |
| red | Make the progress bar red (default). | |
| controls | 0 | Don't show the controls (play, pause, etc.) |
| 1 | Show controls and load Flash right away. | |
| 2 | Show controls, and load Flash once playback starts (default) | |
| https | no | Use http to play back the video (default) |
| yes | Use https to play back the video. | |
| info | no | Don't show video information |
| yes | Show video information. If a playlist is playing, show the video thumbnails. (default) | |
| loop | no | Don't loop the video (default) |
| yes | Loop (repeat) the video, | |
| related | no | Don't show related videos. |
| yes | Show related videos (default). | |
| theme | dark | Display controls within a dark control bar (default) |
| light | Display controls within a light control bar. |
The following parameters will work with everything except EmbedPlus or if IFRAME uses HTML5:
| parameter | option | description |
| annotation | no | Don't show annotations |
| yes | Show annotations (default) | |
| cc | no | Don't show closed caption subtitles (default) |
| yes | Show closed caption subtitles | |
| disablekb | no | Don't disable keyboard controls (default) |
| yes | Disable keyboard controls | |
| link | no | Don't show a link to the YouTube page for the video. |
| yes | Show a link to the YouTube page for the video. | |
| search | yes | Create a playlist based on a search word. The search word should be specified instead of a video ID. See Automatically Generated Playlists for more details |
| user | yes | Create a playlist based on a user's uploads. The search word should be specified instead of a video ID. See Automatically Generated Playlists for more details |
The following parameters will not work if IFRAME uses HTML5:
| parameter | option | description |
| stop | seconds | Stops the video at a specific time, given in seconds. |
The following parameters are only for use with EmbedPlus:
| parameter | option | description |
| hd | If present, play the video in HD quality if possible | |
| react | no | Hide the real-time Reactions buttons (default). |
| yes | Show the real-time Reactions buttons | |
| sweetspot | no | Don't find sweet spots for the next/prev buttons. |
| yes | Find sweet spots for the next/prev buttons |
Alternative Shortcodes
Within your WordPress administration page, select Options from the YouTube menu to see a list of general options:
One section is named Alternative Shortcodes and allows you to specify two additional shortcodes - these will work exactly the same as the standard shortcode of [youtube].
There are two reasons why you might want to do this...
- If migrating from another plug-in, it may use a different shortcode - more details can be found in the section named "Migration".
- If another plug-in uses the same shortcode (e.g. Jetpack) this will allow you to specify and use an alternative.
Each of the new shortcodes can also have their own default profile assigned to them (see Profiles for more details).
Function Calls
As well as a shortcode you can also use a PHP function call to display a video (e.g. in a sidebar). The function is named youtube_video_embed and has two parameters - the first is the video ID (or URL) and the second is a list of display parameters. The display parameters are the same as those used in the shortcode but are separated by an ampersand. example:
youtube_video_embed( 'Z_sCoHGIpU0', 'width=300&height=200' );
Widgets
Sidebar widgets can be easily added. In Administration simply click on Widgets under the Appearance menu. YouTube Embed will be one of the listed widgets. Drag it to the appropriate sidebar on the right hand side and then choose your video options - any that aren't specified are taken from your default profile.
If you wish to display an automatically generated playlist based on user name or search term, simply change the ID Type appropriately and then specify the name or search word(s) where the video ID would normally be entered.
And that's it! You can use unlimited widgets, so you can add different videos to different sidebars.
Both in the profile and as a parameter you can specify a template. This allows you to define any CSS that you wish to "wrap" around the YouTube output.
The template consists simply of any HTML that you wish but with `%video%` where you wish the video to appear. Example:
<div align="center">%video%</div>
Note: When adding templates via a parameter, any HTML included may cause your video to have <pre> tags wrapped around it. The easiest way to check and fix this is to view any post in the HTML editor and remove any <pre> tags that have been added.
Profiles
You've probably already had a look at the default profile, accessible by selecting Profiles from the YouTube administration menu option. Here you can specify the default option which will apply to any embedded video.
However, in the top right hand corner is a drop-down box and a button marked Change Profile. Simply select an alternative profile and click the button and you can then edit the options for this alternative profile. You can even name it as well.
To use this profile, simply use the shortcode parameter profile= followed by the profile name or number.
This can be useful for having a separate profile for different parts of your site - posts, sidebar, etc - or for different video types (e.g. wide-screen).
By default you have 5 extra profiles - if you wish to have more (or less) this number can be changed from the `Options` sub-menu.
Playlists
YouTube allows users to create their own playlists - collections of videos that can be played in sequence. Vixy YouTube Embed supports this as well.
Simply specify the ID of the playlist with the standard methods. To use this playlist (http://www.youtube.com/playlist?list=PLBFE87F034F2FF4BE), the shortcode is:
[youtube]PLBFE87F034F2FF4BE[/youtube]
Note: Playlists cannot be used along with the EmbedPlus embedding method.
A better alternative to playlists is the build-in lists function in Vixy YouTube Embed - see Custom Playlists for further details.
Custom Playlists
Although Vixy YouTube Embed will play standard YouTube playlists, their playback options are limited, so this plug-in lets you create your own, more powerful custom video playlists.
Under the YouTube administration menu select the Lists option. You will be shown a screen where you can type in a list of video IDs (or URLS). You can also provide a name for the list.
As with profiles you can select the list from a drop down in the top right-hand corner. You can also change the number of lists from the Options sub-menu.
To use a list, simply specify the list name or number instead of a video ID in your shortcode. Example:
[youtube]List 1[/youtube]
There is also a list parameter which lets you decide how to play the list. You can either play each in turn, play them randomly, or have just one played at random.
Transcripts
Some YouTube videos include transcripts - a text output of the speech from the video with timings added. These are available in XML format and can be displayed in your post via a function call or shortcode, .
The shortcode transcript will display the transcript in your post along with the start time for each line. Simply supply the video ID as a parameter.
[transcript]MSPsrhCPt-0[/transcript]
If no transcript exists, nothing will be shown.
For style purposes, the `SPAN` around the time has a class of `TranscriptTime`, the `SPAN` around the text has a class of `TranscriptText` and the `DIV` around the whole transcript output has a class of `Transcript`. You can set up your own CSS to format transcripts in this way.
If you wish to use a PHP function call to get the transcript, then you would use the call get_youtube_transcript( ID ), where ID is the video ID.
In all of these cases, the original XML format has been changed to a readable output. If you'd like to return the original XML format, then you can use the call get_youtube_transcript_xml( ID ).
Automatically Generated Playlists
Vixy YouTube Embed includes the ability to automatically generate playlists based upon a user name or a search name. Simply use the user or search parameter to switch the appropriate option on. Instead of a video ID or URL, specify either the user name or search word(s), like this:
[youtube search=yes]Blake Griffin[/youtube]
[youtube user=yes]NBA[/youtube]
Migrating from Other Plug-ins
Within your WordPress administration page, select Options from the YouTube menu, then scroll to the Migration section. There are two boxes that can be checked to activate two different types of alternative embedding - these have been provided to allow easy migration from other similar plug-ins. You can also assign a specific profile to these migrated options.
The Bracket Embedding option allows YouTube URLs to be assigned within brackets - similar to shortcodes but without the actual shortcode name. Example:
[http://www.youtube.com/watch?v=Z_sCoHGIpU0]
The Alternative Embedding option activates a shortcode of other alternative embedding methods.
Deploying these will impact performance, so they should only be used if absolutely necessary.
Thumbnails
Vixy YouTube Embed can add a thumbnail to any part of your theme (sorry, this doesn't work with playlists). There are two methods you can use for this - a shortcode or a function call. The function call looks like this:
youtube_thumb_embed( 'id', 'parameters', '', 'alt', 'nolink' )
Like the video embed equivalent, id is the video ID and alt is the alternative text for the thumbnail image (optional). nolink, if set to true, will output the thumbnail without a link to the YouTube video, allowing you to add your own.
The parameters (separated by ampersands) are as follows...
rel - specify a REL override, e.g. rel="nofollow"
target - specify a TARGET override, e.g. target="_blank"
width - this specifies the width of the thumbnail image
height - this specifies the height of the thumbnail image
alt - specify some ALT text for the thumbnail image. (Supported by shortcode method only).
version - which version of the thumbnail to use. Options are:
- default - use the default thumbnail.
- hq - use a high quality version of the default image.
- start - take the thumbnail from the start of the video.
- middle - take the thumbnail from the middle of the video.
- end - take the thumbnail from the end of the video.
Example function call:
youtube_thumb_embed( 'Z_sCoHGIpU0', 'rel=nofollow&target=_blank', '', 'Demo Video' )
The shortcode method looks like this:
[youtube_thumb target="_blank" alt="Demo video"]Z_sCoHGIpU0[/youtube_thumb]
You can also use nolink as a parameter with the shortcode, which works in the same way as with the function call.
Showing the Video Name
You can retrieve the name of a video in two ways:.
1. Call the PHP function get_youtube_name, passing it to the video URL or ID - this will return the name of the video. Example:
echo get_youtube_name( 'Z_sCoHGIpU0' );
2. Use the shortcode [youtube_name], again passing the video URL or ID. The video name will be displayed. Example:
[youtube_name]Z_sCoHGIpU0[/youtube_name]
Using Shortened URLs
You may return a short URL for any YouTube video by way of either a function call or a shortcode.
For a function call add youtube_short_url( 'id') to your code to return a URL (note that this is not written out, but returned as a value), where id is the video ID.
<a href="<?php echo youtube_short_url( 'Z_sCoHGIpU0' ); ?>"Click here for video</a>
This will create a link to a video using the short URL standard.
To use the shortcode method simply insert [youtube_url id=xx] anywhere within a post to return a shortened URL. xx is the ID of the video. Example:
[youtube_url id=Z_sCoHGIpU0]
Caching
Caches are used to improve plug in performance. Under the YouTube administration menu, locate Options and find the section named Performance. There are three cache options:
- Embed Cache - this is how long to store the resulting cache code. It will update if you change any parameters so, theoretically, shouldn't need to change. It defaults to 24 hours.
- Video Information Cache - video IDs are checked with YouTube to ensure that they're valid. This option lets you to specify how often this should be checked. This defaults to 1 hour.
- Transcript Cache - how long to store transcripts. Defaults to 24 hours.
In all cases setting the cache to 0 will switch off caching for that option.
Further Embedding Options
Under the YouTube administration menu, click Options and find the section named Embedding. There are three options here:
- Add Metadata - by default, RDFa metadata is added to video output. This can be switched on or off as required (see the FAQs for more information about metadata usage).
- Comment Embedding - tick this to allow YouTube URLs added to comments to be converted to embedded videos.
- Feed - videos will not appear in feeds so use this option to decide whether you want them to be converted to links and/or thumbnails.
In the case of URL and comment embedding a profile can be selected.
Metadata
Rich metadata is added to the code generated by Vixy YouTube Embed. This gives details about the video for the purposes of search engines and other rich content interests.
To test the results you can use the Google Rich Snippets Testing Tool. For Google to use your metadata you must apply to be white listed.
EmbedPlus Support
EmbedPlus is an alternative embedding method which adds new features to the standard player. The best way to learn about these new features is to visit the EmbedPlus website. Vixy YouTube Embed also supports EmbedPlus.
EmbedPlus does not support non-Flash methods but will revert to the HTML5 player in circumstances where Flash is not available.
The Chromeless Player
The Chromeless player uses the Flash AS3 player but removes all controls and styling from the resulting video. It has the same restrictions as the standard AS3 Flash player and some of the profile options may not work as usual. For example, the option to display player controls won't work due to the fact that there aren't any.
The Chromeless player can be recreated by switching off controls and all other styling for other video types. However, once a video has been started in the Chromeless player the user cannot stop it – this cannot be created with other player types.
Make Money from Vixy YouTube Embed
With an affiliate account from Shareasale, every embedded video is an opportunity for you to earn extra money from the sale of Jaksta video downloading and recording products. If a web site visitor clicks one of the links below the video and orders, you'll make an average of $13, or 30% of the total sale.
Simply sign up to Shareasale and supply your affiliate ID in the Options screen under Affiliates. Make sure you don't disable the download option (it's enabled by default).
Licence
This WordPress plug in is licensed under GPLv2 (or later),