Getting Started

What is YouTube Media Converter?

YouTube Media Converter is a very fast, high-quality YouTube to MP3 Converter and Video Downloader.

Minimum Requirements

• Linux Server (All Linux distributions supported)
• Works with any hosting plan (Shared*, Dedicated, VPS, etc.)
• Apache or Nginx
• PHP 5.6 or later (PHP 8 is not yet supported)
• PHP exec() and proc_open() functions enabled
• PHP GD extension
• cURL and PHP cURL extension
• FFmpeg and libmp3lame codec (One-click install available!)
• Apache's mod_rewrite (Nginx rewriting instructions)
• MySQL/MariaDB and PHP MySQLi extension
• ionCube Loader
• YouTube API Key (free)
• 50 MB Disk Space on Server

* Note: If you are using a shared hosting plan, please ensure that FFmpeg and cURL are installed.

Features

• Converts YouTube video to MP3 in milliseconds, at qualities up to 320kbps
• Leverages the power of FFmpeg to create crisp, clean, quality, video-to-MP3 conversions
• Downloads YouTube videos directly to MP4, WEBM, MKV, M4A, and 3GP formats
• Supports the download of HD and Ultra HD video streams (2k, 4k, and 8k), if available
• Enables website visitors to crop/cut MP3 files by specifying video start and end times
• Allows users to download all but MP3 formats directly from YouTube, bypassing your server and saving bandwidth
• Downloads/Converts encrypted YouTube (e.g., Vevo channel) videos
• Provides the means to optionally cache "popular" MP3 files, significantly reducing the consumption of server resources (primarily CPU and bandwidth)
• Enables video preview as well as audio playback (via Integrated Music Player) prior to download/conversion
• Integrates YouTube Search (accepts search term, video page URL, or playlist URL)
• Displays Top Videos (filterable by Country)
• Fully optimized for SEO, featuring dynamic Meta and Open Graph tags, dynamic image shares, automatic generation of robots.txt and XML sitemaps, video search URLs/links, and progressive enhancement to facilitate search bot crawling
• Includes 2 JSON REST APIs and a Button/Iframe API to facilitate software integration in a variety of use-case scenarios
• Enables multi-language support via easy-to-add (and easy-to-edit!) translation files
• Requires very little disk space because downloaded/converted files are not stored on server (when MP3 caching is disabled)!
• Effortlessly configure a multitude of software options via an easy-to-read Config file
• Includes a "Config Check" utility to facilitate the software's installation and help resolve any issues with the server configuration
• Features a simple, one-click installation of both FFmpeg and cURL (via the included "Config Check" utility)!
• Facilitates the addition of more pages via common header, footer, and CSS files
• Employs "YouTube.com search scraping" by default to minimize YouTube API consumption
• Optionally rotates between multiple YouTube API keys to effectively extend API usage limits
• Optionally rotates between multiple outgoing IPs to circumvent temporary YouTube IP bans and/or CAPTCHAs that may occur when 1) scraping YouTube.com for video info/links, 2) scraping YouTube.com for search results, and/or 3) downloading videos.
• Automatically caches YouTube API requests (and "YouTube.com search scraping" results) to even further minimize API consumption, reduce the number of API keys required, and speed up load time of video charts and search results pages
• Provides mechanism to block the download/conversion of specific videos at the behest of copyright holders
• Features a completely "responsive" default design (leveraging the Bootstrap framework) to provide optimal viewing for ALL device types and sizes!
• Programmed entirely in easy-to-read PHP OOP (Object Oriented Programming), JavaScript/jQuery, and CSS
• Enables effortless editing/customization of code
• Leverages MVC coding principles to enable templating and clear separation of presentation and business logic

---

Server Configuration

When in doubt, have a pro admin or hosting provider install the required dependency packages for you. Alternatively, we can also perform the server setup for an additional cost.

For the "Do-It-Yourselfers", general command-line instructions (for installing ALL required software dependencies) are available for the following, popular Linux distributions:

(Note: These instructions are provided as a convenience and courtesy to you. They are not a substitute for a professional server configuration. Generally, it is not our responsibility to teach you how to install and configure packages on, or administer and maintain, a Linux system.)

Stop!!  Before continuing, we strongly recommend installing the free aaPanel hosting control panel instead of using the command line to achieve a comparable server configuration. aaPanel will also facilitate the installation of the ionCube Loader, another software requirement that must be installed after all other requirements have been met/installed.

Debian 7 (Wheezy) and Debian 8 (Jessie)

Update Sources

apt-get update

Install Apache Webserver and PHP 5

apt-get install apache2 php5

Create your Domain Directory

mkdir /var/www/YOURDOMAIN.COM

Change Domain Directory Owner

chown www-data:www-data /var/www/YOURDOMAIN.COM

Install text editor "nano"

apt-get install nano

Create Apache vHost

nano /etc/apache2/sites-enabled/YOURDOMAIN.COM.conf

Add the following to the file (via nano), then Press Ctrl + O to save the file and Ctrl + X to close the nano editor:

<VirtualHost *:80>
	DocumentRoot "/var/www/YOURDOMAIN.COM"
	ServerName YOURDOMAIN.COM
	ErrorLog ${APACHE_LOG_DIR}/error_YOURDOMAIN.log

	<Directory /var/www/YOURDOMAIN.COM>
		AllowOverride All
	</Directory>
</VirtualHost>

Enable Apache's "mod_rewrite"

a2enmod rewrite
/etc/init.d/apache2 restart

Install GD PHP Extension

apt-get install php5-gd

Install cURL and cURL PHP Extension

apt-get install curl php5-curl

Note: The following steps are optional. The software already has a built-in FFmpeg auto-installer!

Add Debian Multimedia Repo Sources List for FFmpeg and Codecs

nano /etc/apt/sources.list.d/deb-multimedia.org.list

Add the following to the file (via nano):

• For Debian 7 (Wheezy)

  • # Debian Multimedia Repository 
    deb http://www.deb-multimedia.org wheezy main non-free 
    deb http://www.deb-multimedia.org wheezy-backports main

• For Debian 8 (Jessie)

  • # Debian Multimedia Repository 
    deb http://www.deb-multimedia.org jessie main non-free 
    deb http://www.deb-multimedia.org jessie-backports main

• Press Ctrl + O to save the file
• Press Ctrl + X to close the nano Editor

Update Sources

apt-get update

Install "deb-multimedia-keyring"

apt-get install deb-multimedia-keyring

Update Sources

apt-get update

Install FFmpeg

apt-get install ffmpeg

Ubuntu 12.04, Ubuntu 14.04, and Ubuntu 16.04

Update Sources

sudo apt-get update

Install Apache Webserver and PHP

• For Ubuntu 12.04 and 14.04

  • sudo apt-get install apache2 php5

• For Ubuntu 16.04

  • sudo apt-get install apache2 php7.0

Create your Domain Directory

sudo mkdir /var/www/YOURDOMAIN.COM

Change Domain Directory Owner

sudo chown www-data:www-data /var/www/YOURDOMAIN.COM

Install text editor "nano"

sudo apt-get install nano

Create Apache vHost

sudo nano /etc/apache2/sites-enabled/YOURDOMAIN.COM.conf

Add the following to the file (via nano), then Press Ctrl + O to save the file and Ctrl + X to close the nano editor:

<VirtualHost *:80>
	DocumentRoot "/var/www/YOURDOMAIN.COM"
	ServerName YOURDOMAIN.COM
	ErrorLog ${APACHE_LOG_DIR}/error_YOURDOMAIN.log

	<Directory /var/www/YOURDOMAIN.COM>
		AllowOverride All
	</Directory>
</VirtualHost>

Enable Apache's "mod_rewrite"

sudo a2enmod rewrite
sudo /etc/init.d/apache2 restart

Install GD PHP Extension

• For Ubuntu 12.04 and 14.04

  • sudo apt-get install php5-gd

• For Ubuntu 16.04

  • sudo apt-get install php7.0-gd

Install cURL and cURL PHP Extension

• For Ubuntu 16.04

  • sudo apt-get install curl php7.0-curl

• For Ubuntu 12.04 and 14.04

  • sudo apt-get install curl php5-curl

• For Ubuntu 12.04

  • Open '/etc/php5/apache2/php.ini' and add this line

    extension=curl.so

  • Restart Apache

    sudo /etc/init.d/apache2 restart

Note: The following steps are optional. The software already has a built-in FFmpeg auto-installer!

Install FFmpeg

• For Ubuntu 12.04 and 16.04

  • sudo apt-get install ffmpeg

• For Ubuntu 14.04

  • Add FFmpeg Repo

    sudo add-apt-repository ppa:kirillshkrogalev/ffmpeg-next

  • Update Sources

    sudo apt-get update

  • Install FFmpeg

    sudo apt-get install ffmpeg

CentOS 6.x and CentOS 7.x

Install Apache

yum install httpd

Install wget & gcc

yum install wget gcc

Install epel repo

• For CentOS 6.x

  • wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm 
    rpm -Uvh epel-release-6-8.noarch.rpm

• For CentOS 7.x

  • wget http://dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/epel-release-7-11.noarch.rpm 
    rpm -Uvh epel-release-7-11.noarch.rpm

Install PHP and the cURL and GD PHP extensions

yum install php php-devel php-gd php-common

Enable mod_rewrite

nano /etc/httpd/conf.modules.d/00-base.conf

• Add or uncomment the following line:

  • LoadModule rewrite_module modules/mod_rewrite.so

Create Apache vHost

nano /etc/httpd/sites-available/YOURDOMAIN.COM.conf

Add the following to the file (via nano), then Press Ctrl + O to save the file and Ctrl + X to close the nano editor:

<VirtualHost *:80>
	DocumentRoot "/var/www/YOURDOMAIN.COM"
	ServerName YOURDOMAIN.COM
	ErrorLog ${APACHE_LOG_DIR}/error_YOURDOMAIN.log

	<Directory /var/www/YOURDOMAIN.COM>
		AllowOverride All
	</Directory>
</VirtualHost>

Restart Apache

/etc/init.d/httpd restart

Note: The following steps are optional. The software already has a built-in FFmpeg auto-installer!

Install FFmpeg

• Download a precompiled version of FFmpeg
  • If you want a precompiled version of FFmpeg + codecs for your CentOS server, then you can download a recent static build of FFmpeg here.
  • Use the x86_64 build for 64-bit servers and the x86 build for 32-bit servers.
  • Decompress the corresponding tar.xz distribution, and locate the 'ffmpeg' binary file.
  • To install this build, simply upload the 'ffmpeg' binary file to your "/usr/bin" directory and change permissions of the file to chmod 0755 or higher. And, presto, you have a fully-functioning CentOS build of FFmpeg + codecs, compatibile with our software, that you did not have to compile yourself!
• OR, Compile FFmpeg from source

  • Get the dependencies

    yum install autoconf automake gcc-c++ libtool make nasm pkgconfig zlib-devel git

  • Make a directory in “/root/” to put all of the source code into:

    cd /root 
    mkdir ~/ffmpeg_sources

  • Build/Install FFmpeg and codecs as follows

    • Yasm

      cd ~/ffmpeg_sources 
      curl -O http://www.tortall.net/projects/yasm/releases/yasm-1.2.0.tar.gz 
      tar xzvf yasm-1.2.0.tar.gz 
      cd yasm-1.2.0 
      ./configure --prefix="$HOME/ffmpeg_build" --bindir="$HOME/bin" 
      make 
      make install 
      make distclean 
      export "PATH=$PATH:$HOME/bin"

    • libmp3lame

      MP3 audio encoder.
      Requires FFmpeg to be configured with --enable-libmp3lame

      cd ~/ffmpeg_sources 
      curl -L -O http://downloads.sourceforge.net/project/lame/lame/3.99/lame-3.99.5.tar.gz 
      tar xzvf lame-3.99.5.tar.gz 
      cd lame-3.99.5 
      ./configure --prefix="$HOME/ffmpeg_build" --bindir="$HOME/bin" --disable-shared --enable-nasm 
      make 
      make install 
      make distclean

    • FFmpeg

      cd ~/ffmpeg_sources 
      git clone --depth 1 git://source.ffmpeg.org/ffmpeg 
      cd ffmpeg 
      PKG_CONFIG_PATH="$HOME/ffmpeg_build/lib/pkgconfig" 
      export PKG_CONFIG_PATH 
      ./configure --prefix="$HOME/ffmpeg_build" --extra-cflags="-I$HOME/ffmpeg_build/include" --extra-ldflags="-L$HOME/ffmpeg_build/lib" --bindir="$HOME/bin" --extra-libs=-ldl --enable-gpl --enable-nonfree --enable-libmp3lame 
      make 
      make install 
      make distclean 
      hash -r 
      . ~/.bash_profile

    • After all of this, FFmpeg will be compiled into "/root/bin/ffmpeg".

    • Move the FFmpeg binary file from “/root/bin/ffmpeg” to “/usr/bin/ffmpeg”. Then set permissions of “/usr/bin/ffmpeg” to chmod 0777.

      mv /root/bin/ffmpeg /usr/bin/ffmpeg
      chmod 0777 /usr/bin/ffmpeg

---

Software Installation

Get YouTube API Key

1. Navigate to the Google Developers Console and click "Create Project".

2. Enter a Project Name and click the "Create" button.

3. Click on the "YouTube Data API" link.

4. Click the "Enable" button.

5. Click the "Go to Credentials" button.

6. Select "Web server" from the "Where will you be calling the API from?" menu, select "Public data" for "What data will you be accessing?", and then click the "What credentials do I need?" button.

7. Copy and save your API key to a safe place, and then click the "Restrict key" link.

8. For "Key restriction", choose "None", and then click the Save button. (Note: It may take up to 5 minutes for the API key settings to take effect. So, please wait at least 5 minutes before running the software's "Config Check" utility, to ensure that the "YouTube API Keys" test passes!)

---

Using Multiple API Keys

You may use one or more YouTube API keys with this software. While "YouTube.com search scraping" will dramatically reduce API consumption, the use of multiple keys can serve as a supplemental means to effectively extend the daily API quota/limit.

A new, separate Google account should be created for each new API key that you use with this software. For each Google account, please follow the provided instructions for generating a YouTube API key.

Your API key(s) must be inserted into the $_youtubeApiKeys array in "lib/Config.php". If you supply multiple keys, then one key is randomly selected from this array per request.

---

Configure Settings

Unpack/Unzip the distribution file, open "lib/Config.php", and edit:

Required Settings

Add your License Key

// License Key received at the time of software purchase. 
// You can also login and find it here: https://shop.rajwebconsulting.com/clientarea.php
const _LICENSE_KEY = 'YOUR_LICENSE_KEY_HERE';

Update MySQL database credentials

// Database login info for ALL database tables
// The SAME database is used for software licensing, IP Rotation (see below), or both.
const _SERVER = 'localhost';
const _DB_USER = 'DATABASE_USER';
const _DB_PASSWORD = 'DATABASE_PASSWORD';
const _DATABASE = 'DATABASE_NAME';
// Database table that stores software license's local key
// This table is created "automatically" by the software's initial "Config Check" utility
// OR, see "ymckey.sql" in the "/docs" folder for the SQL required to "manually" build this table.
// (Note: In the vast majority of use cases, you should NOT change the "ymckey" default value!)
const _DB_LOCAL_KEY_TABLE = 'ymckey';

Set the FFmpeg path

// FFmpeg Server Path - usually "/usr/bin/ffmpeg" or "/usr/local/bin/ffmpeg"
const _FFMPEG_PATH = "/usr/bin/ffmpeg";

Set the cURL path

// cURL Server Path
const _CURL_PATH = "/usr/bin/curl";

Set your YouTube API Key or Keys

// YouTube API Keys (Get API Keys from https://console.developers.google.com and/or review '/docs/#youtubeAPI' and '/docs/#youtubeAPIMultiple').
// You may have one or more API keys. If you have multiple keys, then one is randomly selected from the array per request.
// The use of multiple keys enables you to effectively extend the daily API quota/limit and is recommended for sites with moderate-to-heavy traffic.
public static $_youtubeApiKeys = array(
	"123abc456dfg789HiJkL0",
	"0LkJiH987gfd654cba321"
);

Set the App Root directory

// The root directory and location of the application, relative to the web root.
const _APPROOT = '/';  // Directory names must be preceded and followed by a '/'. A value of '/' indicates the web root directory.

Advanced Settings

Website Name (appears in navbar)

// Website Name (appears in navbar)
const _WEBSITE_NAME = "MyConverterSite";

Website Domain (appears in footer and downloaded/converted file name branding)

// Website Domain (appears in footer and downloaded/converted file name branding)
const _WEBSITE_DOMAIN = "MyConverterSite.com";

Default "Country Group", e.g., "Americas", "Europe", or Add Your Own (Required for Charts feature!)

// Default "Country Group"
// Value can be a continent name or any name that you choose to categorize a group of countries in the Config::$_countries array.
// The default available values are "Africa", "Asia", "Americas", "Europe", and "Oceania".
const _DEFAULT_COUNTRY_GROUP = "Americas";

Default Country (Must be within the Default "Country Group"!)

// Default Country
// Must be a valid, lowercase, ISO 3166-1 alpha-2 country code
// Scroll down to $_countries array to see default list of available countries.
const _DEFAULT_COUNTRY = "us"; 

Default Language (Must be included in "app/Languages/index.php"!)

// Default Website Language
const _DEFAULT_LANGUAGE = "en";  // You MUST choose from available languages in "app/Languages/index.php"

Facebook widget settings

const ENABLE_FACEBOOK_LIKE_BOX = true; // Enable or disable Facebook Like Box in Sidebar
const FACEBOOK_PAGE_NAME = "facebook";  // E.g., https://facebook.com/{Facebook page name}

Sharing Buttons (AddThis widget) settings

// Social sharing buttons (AddThis) settings
// Visit https://www.addthis.com/get/share/ to create an account and generate buttons
// You must select "Inline" Tool Type from the AddThis configurator
// _ADDTHIS_SCRIPT_URL and _ADDTHIS_CSS_CLASS values can be extracted from generated button codes
const _ENABLE_ADDTHIS_WIDGET = false;
const _ADDTHIS_SCRIPT_URL = "WIDGET_SCRIPT_URL";
const _ADDTHIS_CSS_CLASS = "addthis_inline_share_toolbox";

Active Site Template ("default" and "xeon" templates available)

// Template Folder Name
const _TEMPLATE_NAME = "default"; // "default" and "xeon" templates available

Video Results per Page (number of initial results and results returned by "Load more videos" button)

// Number of additional video results returned when the "Load more videos" button is clicked
// (FYI - Maximum number of "total possible" search results is 50 !!)
// (Note: This value is also used when search results are obtained via YouTube.com search scraping instead of the YouTube API!)
const _RESULTS_PER_PAGE = 5;

Leverage YouTube.com Search Scraping instead of the YouTube API for some (or nearly all!) requests

// Enable YouTube.com Search Scraping
const _ENABLE_SEARCH_SCRAPING = true; // When true, search results are generated by "scraping" search results directly from YouTube's website, thereby replacing ALL requests to YouTube's "search" API endpoint. Since requests to this endpoint consume the most YouTube API "units", this setting effectively extends the daily quota of your YouTube API key(s), your key(s) will last much longer, and significantly less keys are required for busy sites. By default, search scraping leverages ONLY the primary server IP. Optionally, and alternatively, you can instead enable IP rotation (by setting _ENABLE_IP_ROTATION_FOR_SEARCH to true and using IPs in the _DB_IPS_TABLE2 database table, below) for YouTube.com search scraping requests.
const _SEARCH_SCRAPING_POPULATES_VID_INFO = false; // When true, and _ENABLE_SEARCH_SCRAPING is also true, search results will be populated with video data derived directly from YouTube.com search scraping, thereby eliminating YouTube API requests that would otherwise be made to BOTH the "search" AND "videos" endpoints. Minor and/or infrequent exceptions include "Top Videos" charts, playlist searches, and scraped video page URL searches that return no results (which still rely on requests to the YouTube API's "videos", "playlistItems", and "videos" endpoints, respectively). Thus, this setting ensures that the vast majority of keyword searches uses no YouTube API "units", further reducing (and nearly eliminating) API consumption.

Enable YouTube Direct download (download directly from YouTube servers)

// Enable YouTube Direct download (true = enabled, false = disabled)
const _YOUTUBE_DIRECT_DOWNLOAD = true;

Set Website Interface and Access Control (e.g., if you only need API interface)

// Access Control and Interface for website
// This constant accepts 3 possible values: "web", "api", or "hybrid".
// 1) When set to "web", the default front-end website interface displays. If either or both APIs are "publicly" enabled (see Config::$_apiAllowedDomains, below), then an additional "API" instructions page is visible in site menu links.
// 2) When set to "api", access to front-end website interface is disabled completely, and only direct API access is allowed.
// 3) When set to "hybrid", and either or both APIs are "publicly" enabled (see Config::$_apiAllowedDomains, below), then the default front-end website interface is replaced with an alternate interface that consists of only API, FAQ, and Contact pages. (The "API" instructions page serves as the homepage.) If neither API is "publicly" enabled, then the "hybrid" value behaves the same as "web"!
// See Config::$_apiAllowedDomains, below, to regulate and whitelist API access
const _WEBSITE_INTERFACE = 'web';

Enable/Disable JSON and/or Button/Iframe APIs

// List of domains and/or IP addresses, separated by commas, that are allowed access to the JSON, Button, and JSON "Search" APIs.
// In general, for all APIs, add IP address for PHP consumption and domain for AJAX/HTML consumption.
// If a domain/IP needs access to multiple APIs, then it must be included in each of the corresponding 'json', 'button', and/or 'search' subarrays!
// If the 'json', 'button', or 'search' subarray is empty, then this enables unrestricted, public access to the corresponding API.
// Do NOT prepend domains/IPs with 'http://' or 'https://'!!
// Do NOT prepend domains with 'www' or any other subdomain!!
// IMPORTANT: When using the JSON "Search" API, "both" the _ENABLE_SEARCH_SCRAPING "and" _SEARCH_SCRAPING_POPULATES_VID_INFO constant values (see the "YouTube.com Search Scraping" section above) MUST be set to true in order to eliminate 99.99% of potential YouTube API consumption!!
public static $_apiAllowedDomains = array(
	'json' => array(
		// These are examples. Replace as needed.
		'localhost',
		'mysite.com',
		'123.45.6.789',
		'anothersite.com',
		'187.65.4.321'
	),
	'button' => array(
		// These are examples. Replace as needed.
		'localhost',
		'mysite.com',
		'123.45.6.789',
		'anothersite.com',
		'187.65.4.321'
	),
	'search' => array(
		// These are examples. Replace as needed.
		'localhost',
		'mysite.com',
		'123.45.6.789',
		'anothersite.com',
		'187.65.4.321'
	)
);

Set Available MP3 Qualities

// Available MP3 Qualities, in kbps
// Add/Remove values as needed
// These values are uniformly applied to default website interface "and" included APIs
public static $_mp3Qualities = array(320, 256, 192, 128, 64);

Configure MP3 File Caching

// MP3 Caching Constants
const _CACHE_FILES = false;  // When true, IF a given MP3 file has been converted before AND it is still stored on the server, then the file is delivered directly from the server rather than being downloaded/converted again. This establishes a MP3 file cache on your server, which can significantly save server resources (i.e., bandwidth used for downloading and CPU used for FFmpeg conversions). Note: Only MP3 files are cached at this time because only MP3 downloads require FFmpeg.
const _CACHE_AFTER_X = 2;  // The number of times (greater than zero!!) that a video can be converted to any quality MP3 before it is eventually saved to the cache. (DO NOT set this value to zero!!) E.g., a value of 5 saves an MP3 in the cache after 5 downloads of the same video. This setting ensures that only "more popular" files are cached, which subsequently ensures more efficient use of available cache space (and a generally more effective cache).
const _MAX_ALLOWED_DURATION_DIFFERENCE = 2;  // Value, measured in seconds, used to determine and delete incomplete files in your cache (when caching is enabled). I.e., YouTube's reported video duration is compared to the duration of the cached file on your server. If the difference in durations is more than _MAX_ALLOWED_DURATION_DIFFERENCE seconds, then the corresponding cached file is 1) deemed "incomplete" and 2) deleted from your server.
const _MAX_CACHE_SIZE = 100000000;  // The maximum size, in KB, that the cache folder size can become before the oldest cached files are deleted (via "inc/schedule.php" cron job). Note: Because file deletions are performed as a regularly scheduled task on the server, the actual size of the cache folder may exceed this value between scheduled tasks. So, it is IMPORTANT that this value is set to significantly lower than the actual space available for the cache folder on the hard drive! You can further mitigate this issue by increasing the _CACHE_SIZE_BUFFER constant value, running the scheduled task more often, and/or ensuring that you always have plenty of unused, available hard disk space.
const _CACHE_SIZE_BUFFER = 1000000;  // If the cache folder size is greater than _MAX_CACHE_SIZE, then the oldest files in the cache are deleted one at a time (via "inc/schedule.php" cron job) until the cache size is less than _MAX_CACHE_SIZE minus this value, in KB.

Configure IP Rotation for video info/files "download" and/or "YouTube.com search scraping" requests

// Rotating IPs Constants
// Used to circumvent temporary YouTube IP bans and/or CAPTCHAs that may occur when 1) scraping YouTube.com for video info/links, 2) scraping YouTube.com for search results, and/or 3) downloading videos.
// "IP Rotation" uses either the "ips"/"ips_search" Database table(s) OR the Tor network (see "More Database Constants" and "Tor Constants" sections, below). The default method is the DATABASE METHOD.
// (Note: You can use the DATABASE METHOD or TOR METHOD, but NOT both!)
// (IMPORTANT: The _ENABLE_IP_ROTATION_FOR_SEARCH and _ENABLE_IP_ROTATION_FOR_VIDEOS settings (see below) operate independently, so _ENABLE_IP_ROTATION_FOR_VIDEOS does NOT need to be "true" for _ENABLE_IP_ROTATION_FOR_SEARCH to work, and vice versa. Furthermore, with exception to _DISABLE_IP_FOR_DOWNLOAD, _ENABLE_IP_ROTATION_FOR_SEARCH uses the exact SAME "Rotating IPs Constants" section values that _ENABLE_IP_ROTATION_FOR_VIDEOS does or would. E.g., the _IP_ROTATION_METHOD and _IP_REQUEST_TIMEOUT values apply to BOTH the _ENABLE_IP_ROTATION_FOR_VIDEOS "and" _ENABLE_IP_ROTATION_FOR_SEARCH settings.)
const _ENABLE_IP_ROTATION_FOR_VIDEOS = false;  // When true, enables IP rotation (using IPs in the _DB_IPS_TABLE database table, below) for all YouTube requests related to 1) scraping YouTube.com for video info/links AND 2) downloading videos.
const _ENABLE_IP_ROTATION_FOR_SEARCH = false;  // When true, enables IP rotation (using IPs in the _DB_IPS_TABLE2 database table, below) for all YouTube requests related to scraping YouTube.com for search results. (Note: _ENABLE_SEARCH_SCRAPING, above, "must" be set to true for this setting to work!!)
const _IP_ROTATION_METHOD = "sequential";  // Either "round-robin" or "sequential". The "round-robin" method distributes requests equally to each IP in rotation. The "sequential" method uses the same IP for all requests until that IP is banned, and then (and only then) advances to the next IP in rotation. This value only applies to the DATABASE METHOD (and not the TOR METHOD, which always behaves "sequentially").
const _MAX_CURL_TRIES = 10;  // Maximum number of times code tries a HTTP request, regardless of IP rotation method used, before giving up. (When using the DATABASE METHOD, this value will vary depending on the number of IPs in the rotation. The default value (10) is reasonable if there are 5 total IPs in the rotation -- in which case, each IP is maximally used twice for "each" HTTP request before the code gives up and displays an error.)
const _IP_CONNECT_TIMEOUT = 25;  // Maximum time, in seconds, that a given "proxy" IP can attempt to connect to YouTube before timing out. (This value does NOT apply to IPs configured as "interfaces", when using the DATABASE METHOD.) This can be useful when one or more proxies are not working as expected. Note: Be VERY CAREFUL when reducing the default value!! Do not set this value too low, or otherwise valid requests will fail! If you must reduce the default value, do so in small increments until the "bad" proxy or proxies are effectively addressed.
const _IP_REQUEST_TIMEOUT = 35;  // Maximum time, in seconds, that a given "proxy" IP's request to YouTube can persist before timing out. (This value does NOT apply to IPs configured as "interfaces", when using the DATABASE METHOD.) This can be useful when one or more proxies are not working as expected. Note: Be VERY CAREFUL when reducing the default value!! Do not set this value too low, or otherwise valid requests will fail! If you must reduce the default value, do so in small increments until the "bad" proxy or proxies are effectively addressed.
const _IP_BAN_PAUSE = 43200;  // When using the "round-robin" DATABASE METHOD, this is the length of time, in seconds, to wait before checking if a previously banned IP (that is temporarily disabled in the rotation) is still banned. So, after every _IP_BAN_PAUSE seconds, a given banned IP will either be re-enabled in the rotation (if the ban has been released) or it will continue to be disabled for another _IP_BAN_PAUSE seconds.
const _DISABLE_IP_FOR_DOWNLOAD = true;  // When true, the code will first try to use the primary server IP for video/audio file downloads. In this case, the current IP in rotation is only used if the initial download request fails. (Related HTTP requests will still only use the current IP in rotation.) When set to false, an IP in rotation will be used for ALL requests, including video/audio downloads. At this time, a "true" value is recommended because downloads via the primary server IP will generally be faster than proxy downloads (IF you are rotating "proxy" IPs).

// More Database Constants
// (These Database Constants are only used "if" _ENABLE_IP_ROTATION_FOR_VIDEOS and/or _ENABLE_IP_ROTATION_FOR_SEARCH is enabled and Tor is NOT enabled!)
// You CAN use the same IPs in both the "ips" AND "ips_search" Database tables.
// If you get errors when using the DATABASE METHOD, please first ensure that your additional IPs are configured to operate as "outgoing network interfaces" and/or "proxies". If the IPs are configured correctly, then you must add more IPs to the corresponding database table(s)! The number of IPs in rotation is directly proportional to the amount of traffic to your site, so keep adding IPs until you no longer get errors!
const _DB_IPS_TABLE = 'ips';  // Database table that stores IPs used for IP rotation, as per _ENABLE_IP_ROTATION_FOR_VIDEOS above. Use the online tool (https://rajwebconsulting.com/build-sql/) or see "ips.sql" in the "/docs" folder for the SQL required to build this table.
const _DB_IPS_TABLE2 = 'ips_search';  // Database table that stores IPs used for IP rotation, as per _ENABLE_IP_ROTATION_FOR_SEARCH above. Use the online tool (https://rajwebconsulting.com/build-sql/) or see "ips_search.sql" in the "/docs" folder for the SQL required to build this table.

// Tor Constants
// (Tor, when enabled below, is used "instead of" the Database "if" (and "only if") _ENABLE_IP_ROTATION_FOR_VIDEOS and/or _ENABLE_IP_ROTATION_FOR_SEARCH is also enabled!)
const _ENABLE_TOR_PROXY = false;  // Enable the use of Tor for IP rotation (i.e., the TOR METHOD) instead of the default DATABASE METHOD. (See https://hub.docker.com/r/rajwebconsulting/tor-proxy for Tor setup instructions.)
const _TOR_PROXY_PASSWORD = "YOUR_TOR_PASSWORD";  // Tor password used for control protocol request authentication, which is required to change Tor proxy IP.
const _TOR_PROXY_PORT = '9250';
const _TOR_CONTROL_PORT = '9251';

Now upload all files to your web server

Follow the prompts in the subsequent "Config Check" utility, to help resolve any remaining issues with the server or software configuration.

This utility will enable a simple, one-click installation of "both" FFmpeg "and" cURL (IF the corresponding binary files are NOT yet installed and registered as system-wide commands, AND IF your hosting plan permissions allow it). In addition, the utility will enable one-click creation of the software license's "local key" database table (IF the table does NOT yet exist AND you've provided valid database login credentials).

Finally, don't forget to set "store" folder permissions to chmod 0777!

---

FAQ

---

Support

Software Support

Stuff you might like to know about software support:

1. 100% Free support for life!
   • Ask us a question, and we'll answer it!
   • Working directly on your server is not free.
2. Regular updates/fixes to the software are Free!
   • Scroll up to the top of these docs or visit "/inc/update.php" to see if you have the latest version.
   • You will receive email notifications when new versions are released.
   • You can log in and download the software anytime via your customer account portal.
3. See The FAQ for ways to troubleshoot common issues.
4. Human support for this script is provided via:
   • Our ticket system, accessible via your customer account portal (for technical, product support)
   • Our Contact Page (for sales support)

---

Licenses

Regular License

The Regular License permits one, single installation of this software.

If you require additional licenses, then discounted prices for Multiple Licenses are available.

Multiple Licenses

If you plan to load this software on multiple websites/domains and/or run the software (on a single site) in a cluster (a.k.a., multi-server), load-balancing configuration, then you MUST buy additional Regular Licenses.

We offer 2 standard bundle discounts: €20 EUR off a 3-license bundle and €55 EUR off a 6-license bundle.

Custom discounts are also available for non-standard quantities of license purchases. In that case, please contact us to arrange the purchase of Multiple Licenses.

---

Changelog

Software Changelog

Version 1.61 (10.27.2021)

• Fixed a bug that caused HTTP requests to YouTube to fail for servers configured to use HTTP/2
• Corrected header logo size in the "xeon" template on mobile devices
• Fixed a bug in music player that prevented audio playback of other videos in Search Results and Music Charts IF the player was already open
• Fixed a bug that generated incomplete MP3 files in cache IF end user canceled browser download while file was saving to cache
• Improved code that automatically issues/checks software licenses
• Updated some deprecated "getID3" vendor library code
• Implemented various, minor fixes and refactoring of code

Version 1.6 (10.15.2021)

• Decoupled "YouTube.com search scraping" from IP Rotation, so that the latter is no longer a prerequisite for the former
• Enabled YouTube.com search scraping (using the primary server IP) by default
• Improved YouTube.com search scraping such that searches now generally return more results
• Completely overhauled and fortified the YouTube "extractor" file:
  • Scraped video info/links and search results are now obtained from up to 3 different YouTube.com sources
  • I.e., if one source fails, then the next source is tried, and so on -- in an effort to maximize long-term software stability
  • As long as the primary YouTube.com source continues to work (as it does now), then there are "no" IP bans and/or CAPTCHAs
  • IF ever a quota/limit is imposed for requests issued via the primary YouTube.com source, then IP Rotation can be enabled for ANY/ALL YouTube requests
• Discontinued Anti-Captcha Plugin due to its current inability to effectively circumvent IP bans and CAPTCHAs (BUT left Plugin "hooks" in software, in case this changes in the future)
• Updated and enhanced "Config Check" utility to support some new server/software requirements
• Improved music/audio player performance
• Added more countries to Music Charts and corresponding XML sitemaps, and removed countries that are no longer supported
• Improved and expanded scope of software.xml update mechanism
• Updated and improved software documentation
• Implemented ionCube encoding of some files in the "/lib" folder (that are NOT required for software customization) as well as strict enforcement of software licensing
• Fixed FFmpeg conversion issue that could potentially create unwanted "zombie" processes on server (which would consume unnecessary server resources)
• Implemented various, minor fixes and refactoring of code

Version 1.52 (03.15.2021)

• Updated the YouTube "extractor" file:
  • Improved extraction of YouTube download URLs
  • "YouTube.com search scraping" yields more and better quality search results
  • Forced scraped video/search data to use the _DEFAULT_LANGUAGE in "lib/Config.php"
• Improved "Anti-Captcha Plugin" integration and documentation
• Enhanced general effectiveness of "Config Check" utility (that appears during installation)
• Implemented various, minor fixes and refactoring of code

Version 1.51 (10.26.2020)

• Updated and improved extraction of YouTube download URLs
• Added additional security to download URLs (i.e., "@download" requests) to fix an exploit that enabled unauthorized 3rd parties to consume, share, and generally abuse these links
• Generally bolstered the security of other "protected" software requests
• Updated and enhanced "YouTube.com search scraping" functionality, in response to YouTube changes
• Prepped the software for compatibility with new "Anti-Captcha Plugin"
• Implemented various, minor fixes and refactoring of code

Version 1.5 (05.14.2020)

• Added the "YouTube.com search scraping" feature that, when enabled, eliminates the vast majority of YouTube Data API requests that were previously required for keyword searches
• Added the JSON "Search" API, which relies on "YouTube.com search scraping" and functions with little-to-no dependence on the YouTube API
• Included an easy-to-use "proxy checker" tool in the "docs" folder to quickly determine the validity of proxy IPs used for IP Rotation and/or "YouTube.com search scraping"
• Implemented various, minor fixes and refactoring of code

Version 1.48 (02.02.2020)

• Added the "sequential" database and Tor IP rotation methods as alternatives to the original "round-robin" database method
• Removed additional YouTube requests during the generation of Video Streams links (and subsequently sped up Video Streams links generation) by eliminating the validation of nonessential remote file formats
• Improved IP ban/CAPTCHA detection to generally strengthen the integrity of IP rotation
• Updated and improved YouTube download URLs extraction
• Extended "chunked" download option to include low-quality "non-DASH" video formats
• Implemented various, minor fixes and refactoring of code

Version 1.47 (08.22.2019)

• When IP rotation is enabled, the corresponding _DISABLE_IP_FOR_DOWNLOAD constant in "lib/Config.php" is set to "true", and the initial download request sent via the server IP fails, then the code will retry the download with the current IP in rotation
• Download buttons corresponding to cached MP3 files will now be displayed even if there are no available, working IPs
• If all available MP3 qualities for a given video are cached, then additional video info is extracted from a cached MP3 file's metadata instead of from YouTube, to improve download button/link generation speed and eliminate unnecessary YouTube requests
• Added optional "social sharing" button to each video in Search Results and Music Charts, that, when clicked, leverages the AddThis widget inside of the subsequent modal popup window
• Moved list of available MP3 qualities to "lib/Config.php" so that they can be more easily configured
• Fixed issue that sometimes prevented videos with unicode characters in the video title from caching correctly
• Implemented various, minor fixes and refactoring of code

Version 1.46 (07.30.2019)

• Updated YouTube video extraction to accommodate new location of some video data.

Version 1.45 (07.26.2019)

• Further updated the IP rotation mechanism to:
  • Temporarily skip IPs that return a cURL error, cannot connect, and/or take too long to complete a given YouTube request
  • Optionally prevent IPs from being used for video/audio file download requests
  • Force slow downloads to time out eventually, if IPs are used for video/audio file download requests
• Implemented various, minor fixes and refactoring of code

Version 1.44 (07.18.2019)

• Updated the IP rotation mechanism (in response to lower YouTube HTTP request limit per IP) to:
  • Accommodate proxy IPs as well as IPs configured as outgoing network interfaces
  • Enable the use of proxy IPs and interfaces concurrently
  • Skip banned IPs in rotation to facilitate faster release of IP bans
  • Fix bug that was sometimes using IPs in rotation for @download requests (instead of YouTube requests), potentially resulting in uneven use of IPs (for YouTube requests)
• Removed one unnecessary YouTube HTTP request sent during the generation of download links
• Reduced YouTube API units used (to lessen impact on API quota) by replacing more "expensive" search requests with video requests for the following types of URLs and search terms, e.g.:
  • https://yoursite.com/Katy-Perry-Roar-Official-(CevxZvSJLk8)
    • Used for 1) video title links in Search Results / Music Charts and 2) page URLs in XML Sitemaps
  • https://yoursite.com/@shareimg/share-CevxZvSJLk8.png
    • Used for HTML meta "og:image" tags in Search Results
  • https://www.youtube.com/watch?v=CevxZvSJLk8
  • https://youtu.be/CevxZvSJLk8
• Added progress bar for YouTube search results
• Added video thumbnail URL and duration to all JSON API endpoints' output
• Added support for the download of 8k quality video, if available
• Disabled "Content-Length" HTTP header for MP3 downloads, resolving intermittent MP3 download failures in Firefox and/or when Cloudflare/Nginx is used
• Implemented various, minor fixes and refactoring of code

Version 1.43 (06.12.2019)

• Updated and improved YouTube download URL extraction
• Updated and improved the mechanism used to detect encrypted YouTube videos and decrypt them
• Further protected against content scraping (and general abuse) of JSON and Button/Iframe APIs as well as AJAX URLs
• Added ability to enable Google's "Invisible" reCAPTCHA for search form submissions
• Eliminated multiple file extensions in MKV file names
• Implemented various, minor fixes and refactoring of code

Version 1.42 (11.17.2018)

• Changed MP4 file formats to MKV in the "Video Streams" sections of video charts and search results, as well as in the "mergedstreams" option of the JSON and Button/Iframe APIs, to:
  • Fix issue that prevented "seeking" (i.e., moving forwards and backwards) during playback of corresponding downloaded videos on many media players and devices
• Included option in Config file to edit default "MKV" label on download buttons, in JSON API, and at the end of download URLs
• Added file sizes to download buttons in the "Video Streams" sections of video charts and search results, as well as in the "mergedstreams" option of the JSON and Button/Iframe APIs

Version 1.41 (11.15.2018)

• Added a "Video Streams" option to each item listed in video charts and search results, and included a "mergedstreams" option with the JSON and Button/Iframe APIs, that:
  • Increases the number of available "composite" video + audio download options and qualities (including HD and Ultra HD) for a given video
  • Merges "DASH" Video-Only and Audio-Only streams via FFmpeg stream copy
  • Addresses YouTube's recent removal of HD "non-DASH" video download links
• Added ability to show/hide "Videos" and/or "Video Streams" options for each listed item in video charts and search results
• Added ability to show/hide "videos" and/or "mergedstreams" options on the API instructions page
• Enabled optional "chunked" download of all available file types (except low-quality "non-DASH" video formats), to increase download speed when/if YouTube throttles their bandwidth
• Introduced the optional use of high-quality "DASH" audio formats for MP3 conversions
• Improved the quality of search results when searching some video page URLs
• Enabled automatic search form submission when a search suggestion is selected
• Consolidated and reduced the number of requests to YouTube when validating video download URLs
• Fixed bug that could potentially allow multiple users to simultaneously trigger purging of the "links" or "api" cache folders, resulting in attempts to delete nonexistent (i.e., already deleted) cached files
• Implemented complex sorting of all available download formats for any given video to end reliance on YouTube's volatile format order
• Resolved issue that caused an error message to display when cached MP3 files were available but corresponding YouTube download links were otherwise unavailable or nonfunctional
• Implemented various, minor fixes and refactoring of code

Version 1.4 (04.11.2018)

• Introduced optional caching of "popular" MP3 files
• Consolidated and reduced the number of unique YouTube API requests required
• Enabled automatic caching of YouTube API requests
• Added mechanism to block the download/conversion of specific videos at the behest of copyright holders
• Automated installation of FFmpeg and cURL binaries via the software's "Config Check" utility
• Enabled further flexibility of website interface and access control depending on JSON/Button API preferences
• Added multi-language support for additional translations, and added Portuguese language support
• Fixed bug that halted further processing of additional, available YouTube download URLs if any single download URL was determined to be invalid (i.e., if it returned a HTTP 403 response)
• Implemented various, minor fixes and refactoring of code

Version 1.33 (02.26.2018)

• Omitted "Content-Length" HTTP header for MP3 downloads IF the user agent is Firefox (desktop version), resolving intermittent MP3 download failures in Firefox. (Other browsers/platforms are not affected.)

Version 1.32 (02.11.2018)

• Switched to "non-DASH" video formats for MP3 conversion to avoid slow conversions caused by YouTube-imposed throttling of "DASH" audio downloads
• Modified all download URLs to use the "redirector.googlevideo.com" subdomain, to generally improve download availability and performance
• Implemented various, minor fixes and refactoring of code

Version 1.31 (05.05.2017)

• Fixed bug preventing audio playback in Integrated Music Player

Version 1.3 (04.25.2017)

• Added JSON REST API and Button/Iframe API, API instructions page, and corresponding documentation
• Added ability to download all but MP3 formats directly from YouTube, completely bypassing server
• Added ability to download/convert age-restricted YouTube videos
• Added search suggestions and auto-complete to front page search form
• Added "layouts" folder to templates, enabling multiple header/footer files for the same template
• Added ability to disable regular website interface (e.g., if only API is needed)
• YouTube API requests are retried upon failure, using a new API key when multiple API keys are present
• Fixed bug that prevented MP3 downloads when Cloudflare SSL is active
• Implemented various, minor fixes and refactoring of code

Version 1.2 (02.03.2017)

• Added dynamic Meta and Open Graph tags for video searches
• Added dynamic "share images" for video searches
• Automated generation of robots.txt file
• Automated generation of XML sitemap index file and associated XML sitemaps
• Added hreflang values to static pages and sitemap URLs
• Added multi-language support and translation engine
• Automated language and country detection for translations and "Top Music Videos", respectively
• Moved the majority of URL rewriting rules from .htaccess to "app/Core/Router.php"
• Enabled search URLs with the following formats:
  • http://mysite.com/{Keyword or Keywords}
  • http://mysite.com/{Video Id}
  • http://mysite.com/watch?v={Video Id}
  • http://mysite.com/{YouTube Video URL}
• Added search URL link to each video title in search results
• Facilitated search bot crawling of code if JavaScript is "not" enabled
• Implemented various, minor fixes and refactoring of code

Version 1.11 (01.20.2017)

• Fixed the mechanism used to detect encrypted YouTube videos

Version 1.1 (09.30.2016)

• Added support for multiple YouTube API keys, to extend API usage quota limits
• Added "xeon" template to collection of available template designs
• Video preview button now opens the corresponding video in a FancyBox modal window instead of a new tab
• Added protection against content scraping of AJAX URLs
• Added support for more countries in the Top Videos lists
• Fixed downloaded/converted file incompatibility issue with third-party video/audio editors
• Fixed bug that prevented the passing of arguments to "element" files
• Added ability to pass template-specific variable values to generic "page" and "element" files
• Added "url rewriting" test and support for testing multiple YouTube API keys in "Config Check" utility
• Updated the Server Configuration, Software Installation, FAQ, and Changelog sections of these docs

Version 1.01 (07.16.2016)

• Fixed Error 404 page styles, in some cases
• Provided option to forward all http:// requests to https:// via .htaccess
• Fixed bug affecting the video duration format displayed on thumbnail images
• Updated the Server Configuration, FAQ, and Changelog sections of these docs
• Fixed url encoding issue that prevented download of some videos
• Fixed url encoding issue that adversely affected searching with certain keywords