“TuneVoyage” Documentation
TuneVoyage
Build a massive following organically!
Thank you for purchasing TuneVoyage. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here.
Table of Contents
- Overview and features
- How does it work
- Installation & requirements
-
Working with TuneVoyage
-
Getting client ID and secret for each platform
A) Overview and features - top
OVERVIEW
TuneVoyage is a web based application and catalog, that combines powerful tools to help musicians/labels and other content creators organically grow their fan base on various social networks by trading free downloads for social engagement and new followers (via download gates), convert more fans to streams and downloads by better marketing their music with smart links and keep track on the growth.
FEATURES
-
DOWNLOAD GATES are landing pages for your music where you give fans free downloads in exchange for
social support (following you on a social website, liking/reposting your content).
This way you can rapidly grow your SoundCloud, Mixcloud, Spotify, Deezer and/or YouTube fan base!
-
SMART LINKS are landing pages for your music where you can list all of the stores and streaming
services that it's available in and convert more of your fans to streams or downloads. Share and promote
one link!
-
BRIDGES are one of the most unique features, that TuneVoyage has - to combine download gates and
smart links on one page! Some times artists and labels release their music for free, but also publish
it on different streaming services (youtube, spotify, tidal) and music stores, for all of the hardcore
fans who are always there to support! You can create both a smart link page with all of the links to
stores and streaming services that the release is available in and a download gate.
Then you can attach the smart link to the gate and create a "bridge". Bridges are pages that allow
your listeners to decide if they want to unlock the free download for social exchange or choose to
stream/buy from one of the stores listed in your smartlink. "Bridged" smart links are no longer
included as a different item in the catalog, but are still visible in the statistics section in admin.
-
CATALOG with all of your download gates, smart links and bridges that acts as the home page of your system.
There fans can checkout the rest of your content and filter it by the categories (or genres) you have created.
-
DETAILED STATISTICS
- See how your downloads are helping you grow on the different social networks.
- Keep track of the downloads, see where your content was downloaded from and using what platforms.
- Filter the statistics to only show downloads via a given network.
- Check download statistics based on a time period, that you select.
- See what's your most popular song/item.
- See what social networks are most preffered by your fans
- Keep track of the downloads for the week, month and current day.
- Keep track on what stores get most link clicks.
- See where your clicks are comming from (country/city)
- Keep track of the total reposts, made by your fans and see who is the top reposter.
- TuneVoyage will let you know how many new fans you have reached thanks to your free downloads.
- Much, much more ...
-
CUSTOMIZATION OPTIONS Branding is really important, not just for the big labels and artists,
but also for the indipendent ones. This is the reason why TuneVoyage comes with customization
features, like uploading your own label/artist logo, changing the background image, changing the
system/browser title, adding particleground effect + customizing it and more.
-
SHARE BUTTONS Your fans can share the smart links and download gates on Facebook, Twitter, VKontakte, Pinterest and/or Google Plus.
-
EMBED ON OTHER PAGES You can embed your smart links on other pages!
-
API METHODS. If you are an experienced programmer you can use the API methods to do some
cool stuff, like displaying how many downloads you have for the current day/week/month
on your main webiste. You can also "grab" the whole catalog and make a custom designed page for it,
so it matches your website design.
B) How does it work? - top
HOW DOES A DOWNLOAD GATE WORK?
For each download gate you can choose what download options to give to your fans. They can choose one of
the platforms you have included for the gate and connect with their profiles. Once they authorize the
connection they will automaticly follow you on a given social website, repost and/or like your content
(depends on your settings). After that the download will be unlocked. You can choose to display more of
your social media profiles and encourage fans to visit after their download is unlocked (twitter, facebook
page...).
TuneVoyage is really flexible. You can setup different download options and rules for
different gates. You can also upload your files directly to your server or chose to redirect the fans
to another service like zippyshare and dropbox, if you want to save space on your hosting.
HOW DOES A SMART LINK WORK?
You can add all the links to the different stores and streaming services, that your release is available in,
and the system will generate a beautiful landing page with the cover you uploaded, preview (soundcloud or
youtube embedded player) and a custom url you have entered. There your fans can see the list with all the
stores and choose where they want to stream or download from. This way you can promote just one
link in your emails, youtube videos, soundcloud descriptions, blog posts and etc.
Simple and effective! Smart links also help you understand where your clicks are comming from and
what are the most preffered shops.
HOW DOES A "BRIDGE" WORK?
You can attach a smart link to a download gate when creating the download gate. This will automatically combine the
items and create a page where your fans can choose if they want to support you via a purchase (or by streaming your content)
or if they want to follow you and repost your content on social media.
C) Installation - top
TuneVoyage requires apache server; PHP version 5.4 or above (+ cURL), but PHP 7 is recommended; MySQL 5.x;
SoundCloud, Mixcloud, Deezer, Spotify and/or YouTube API key and secret (if you want to use download gates).
-
Unzip the archive and upload the tunevoyage folder to your server via a FTP client.
Make sure you give "777" as permissions to the "uploads" and "application/views/compiled" directories.
-
Create a new database and user in cPanel. When asked, give all priviliges. Import the "install.sql" file in the
database.
-
Open the website (example: http://mywebsite.com/tunevoyage) and enter your database name, user and password then
choose your time zone.
-
On the next step you can choose a custom diplsay name and description for the system, admin e-mail, password and also choose if you want to
use download gates, wich social websites you want your fans to follow you on and add the APP info (client id and secret)
for each of the platforms. You can do this any time later too in the settings page.
Check out "Getting client ID and secret for each platform" if you need more information.
STILL CONFUSED? Watch a video tutorial here.
D) Work with TuneVoyage - top
Admin zone - top
The admin zone is located in the /admin subfolder. Login with your e-mail and password.
-
DASHBOARD
The dashboard is the home page of your admin zone.
Here you can view some quick stats about the downloads, link clicks and more.
-
GATES/LINKS
Here you can create, edit and rearrange your smart links and download gates.
-
CATEGORIES
Here you can create, edit and rearrange your categories.
-
STORES
Activate, deactivate stores/services or rearrange their order (for smart links).
-
STATISTICS
View detailed statistics about downloads, downloaders, clicks, preffered platforms and so much more.
-
SETTINGS
You can change global system settings from this page.
Creating categories - top
The first thing you have to do after you install TuneVoyage is to add some categories. Each category will
appear in the catalog and your fans can filter your releases and find the thing they want faster and easier.
If you work in one genre only you can create categories that match the mood of your songs
(for example: accoustic, live, club, rave, road trip). You decide how to use. If you just want to use one
category it may be better to hide the filter from the catalog because it would be redundant. You can do this
in the settings page.
Creating smart links - top
You can create, delete and edit smart links from the "Gates/Links" page in the admin zone. A smart link needs
at least 1 link to an external music shop or streaming service. You can create a new one by clicking this button:
-
SMART LINK NAME
Each smart link should have a name. Most of the time this will be the name of your song/album/release.
This field is required.
-
KEYWORD
This is going to be used as a custom url for the page. You can use letters from a to z (lower-case only),
numbers 1-9, symbols "_" (underscore) and "-". Do not put whole URLs, just one word, like "mykey".
Example: http://website.com/tunevoyage/mykey
This field is required.
-
AUTHORS
List the authors of the song. Not required.
-
CATEGORIES
Each smart link should be assigned to at least one category. You can add up to 3 categories per link.
This field is required.
-
PREVIEW
YouTube or SoundCloud link. You can leave this field empty. If empty the system will display the cover
of the release that you uploaded instead of the preview. It's also possible to use a SoundCloud playlist link.
This field is not required.
-
SHOPS & SERVICES
Add your links to Beatport, iTunes, Spotify, Deezer, Napster, Bandcamp, Tidal and more...
Fill at least one of these fields.
-
DON'T SHOW IN CATALOG
You can exclude the smart link from the catalog (hide it). The smart link page will still be available
to use for everybody who has the url.
-
PAGE BACKGROUND
You can use the default background, the one you have uploaded or use the cover of the release
(a blured version) as a background for the landing page.
-
COVER FILE
Maximum size should be 2MB.
Allowed file types: .jpg, .jpeg, .gif, .png
Minimum dimensions: 500x500 (1500x1500 is prefered).
If you don't upload a cover for your release, a default one will be used.
Creating download gates (and bridges) - top
IMPORTANT: Please use the gate rules (what your fans must do in order to unlock a download) wisely!
It is not recommended to force fans to follow many artists or like/repost songs, that are not included
in your release. For example, if you are the only author of a song do not add additional profiles to follow
(well... maybe the label, of course). Not only that people might not like the idea to follow someone who they
have never heard of before, but a lot of the platforms also have certain limmits on how much new followings can
be added by a user for a small period of time. SoundCloud may temporarily suspend accounts that "follow more
profiles at once that is humanly possible".
I developed TuneVoyage so it doesn't break any of the DEVELOPERS TERMS OF USE for the different platforms and
there is a reason why it doesn't have unlimmited fields to add many more artists and tracks for the gates or why
it doesn't collect too much sensitive data. If you decide to alter the code of TuneVoyage and add more fields,
you do it at your own risk! If you go against the "developers terms" of any platform your APP might be banned.
It is safe to fill all of the current fields in the download gate rules, but it would be much better to do it ONLY IF YOU REALLY NEED TO.
DON'T SPAM - PROMOTE!
You can only create download gates if at least one of the platforms in the settings page is activated and you have
provided (again, in settings or during installation) API client ID, client secret and a default profile.
The default profile is included in each download gate, when you have selected
the "follow/subscribe to download" option, so you don't have to re-enter your profile/channel url over and
over again when creating new gates.
-
GATE NAME
Each gate should have a name. Most of the time this will be the name of your song/album/release.
This field is required.
-
KEYWORD
This is going to be used as a custom url for the page. You can use letters from a to z (lower-case only),
numbers 1-9 and "_" (underscore). Do not put whole URLs, just one word, like "mykey".
Example: http://website.com/tunevoyage/mykey
This field is required.
-
AUTHORS
List the authors of the song. Not required.
-
CATEGORIES
Each download gate should be assigned to at least one category. You can add up to 3 categories per link.
This field is required. Connect the gate to at least 1 category.
-
PREVIEW
YouTube or SoundCloud link. You can leave this field empty. If empty the system will display the cover
of the release that you uploaded instead of the preview. It's also possible to use a SoundCloud playlist link.
This field is not required.
-
SOUNDCLOUD GATE Register APP here - top
This option will only be visible if you have provided
client ID and secret for SoundCloud.
If you include
this option, a SoundCloud button will appear in the download gate's page that will let your fans connect with
their profiles. After that all of the "rules" bellow will be automatically executed (meaning they will automatically
follow the listed SoundCloud profiles and/or like the listed songs). In the end a download button will appear.
-
YOUTUBE GATE Register APP here - top
This option will only be visible if you have provided
client ID, client secret and API key for YouTube. If you include
this option, a YouTube button will appear in the download gate's page that will let your fans connect with
their profiles. After that all of the "rules" bellow will be automatically executed (meaning they will automatically
subscribe to the listed channels and like the listed videos). In the end a download button will appear.
VERY IMPORTANT! When including a YouTube download gate to your release you should
always just list the IDs of the channels, that you want your fans to subscribe to. When you visit a
channel's page on YouTube look at the browser's address bar.
If the link looks like this
https://www.youtube.com/user/BassOneOfficial
, then it is
not valid to use in TuneVoyage. In this case you need to click on any of the
videos uploaded by the channel and then click on the channel's name bellow the video, next to
the avatar.
Now check the adress bar again. The link should look like this:
https://www.youtube.com/channel/UCmyBcA6xsJDuKn_An6wL-EA
You only need the part after "/channel/", that is the channel ID.
In this example it's
UCmyBcA6xsJDuKn_An6wL-EA.
-
SPOTIFY GATE Register APP here - top
This option will only be visible if you have provided
client ID and secret for Spotify. If you include
this option, a Spotify button will appear in the download gate's page that will let your fans connect with
their profiles. After that all of the "rules" bellow will be automatically executed (meaning they will automatically
follow the listed artists, playlists or/and add the some songs). In the end a download button will appear.
-
DEEZER GATE Register APP here - top
This option will only be visible if you have provided
client ID and secret for Deezer. If you include
this option, a Deezer button will appear in the download gate's page that will let your fans connect with
their profiles. After that all of the "rules" bellow will be automatically executed (meaning they will automatically
follow the listed profiles and favorite the listed songs). In the end a download button will appear.
-
MIXCLOUD GATE Register APP here - top
This option will only be visible if you have provided
client ID and secret for Mixcloud. If you include
this option, a Mixcloud button will appear in the download gate's page that will let your fans connect with
their profiles. After that all of the "rules" bellow will be automatically executed (meaning they will automatically
follow the listed profiles and like/repost the listed mixes). In the end a download button will appear.
-
FILE TO DOWNLOAD
Upload the file that users will download after the procedure. You can also give a link to
external services like zippyshare, dropbox and etc if you don't have enough space on your
host or just want to save some. The second option is highly recommended for large files.
-
CREATE BRIDGE
Create a "bridge" by combining this download gate with a smart link. This will display both the
follow to download and purchase/stream options on the landing page. The attached smartlink will
no longer be visible in the catalog (home page).
-
LOCK AFTER DOWNLOADS
Disable the download gate after a certain amount of downloads. Leave empty or 0 for unlimited downloads.
-
SHOW DOWNLOAD COUNTER
Show the total downloads for this item on it's landing page.
-
DON'T SHOW IN CATALOG
You can exclude the download gate from the catalog (hide it). The download gate's page will still be available
to use for everybody who has the url.
-
PAGE BACKGROUND
You can use the default background, the one you have uploaded or use the cover of the release
(a blured version) as a background for the landing page.
-
COVER FILE
Maximum size should be 2MB.
Allowed file types: .jpg, .jpeg, .gif, .png
Minimum dimensions: 500x500 (1500x1500 is prefered).
If you don't upload a cover for your release, a default one will be used.
Statistics - top
Follow your progress in details with TuneVoyage's statistics!
-
DOWNLOADS BY DATE
When you open this page it will automatically load the details for downloads made during the current month.
You can choose a custom time period and filter statistics to view only downloads unlocked via a specific platform.
-
DOWNLOADS BY GATES
Here you can check how many downloads each of your gates got in total and view a detailed report for a custom time period
for each of the gates.
-
DOWNLOADERS
Information about your top 10 downloaders.
-
LINK CLICKS
Check how many clicks each of your smart links got. Click on a smart link to view details
(what countries/cities are the clicks coming from, when was a link clicked, to what
store/service was the user redirected...).
-
REPOSTS
You can see how many reposts your fans made, who your top reposters are and what is the most reposted item/mix.
-
TOP LOCATIONS
View the top 5 countries and top 5 cities, that downloaded your music and top locations that clicks are comming from.
The Settings Page - top
-
SYSTEM NAME
Choose a custom display name for your download gate system. Leave empty for default.
This will act as a browser title too.
-
CUSTOM DESCRIPTION
This would appear as website description in Google search results, also when sharing on facebook.
-
ADMIN EMAIL
You can change your e-mail here.
-
ADMIN EMAIL
You can change your password here.
-
ACTIVATE PLATFORMS
If you want to be able to create download gates you need to activate at least one of thease platforms.
Do not activate any if you plan to use only to create smart links. Each platform needs a dedicated Web APP in order
to comunicate with TuneVoyage. For each platform, that you want to use you also need to provide API cliend ID,
client secret and a default profile/channel on the same page bellow.
-
DEFAULT PROFILES
You have to enter a default profile for each of the active platforms. That profile will be included in all download gates,
where you have selected the "follow to download" option.
-
REDIRECT URIS
Use these when creating your APPs.
-
SOUNDCLOUD APP
Enter your SoundCloud API client id and secret here.
-
YOUTUBE APP
Enter your YouTube client id, secret and API key here.
-
SPOTIFY APP
Enter your Spotify API client id and secret here.
-
DEEZER APP
Enter your Deezer API client id and secret here.
-
MIXCLOUD APP
Enter your Mixcloud API client id and secret here.
Check out "Getting client ID and secret for each platform" if you need more information.
-
FAQ & TERMS
Write your terms and privicy policy + faq section. Always update the policy and FAQ section if you
change code to collect different or more information from the authenticated users! Your fans should
always know what information is extracted from their profiles.
-
FACEBOOK PAGE PLUGIN
Ask your visitors to also like your facebook page, once the download is unlocked.
-
MORE SOCIAL LINKS
Show more social profiles on the page after the download is unlocked.
You can add your official website, twitter account, instagram profile and facebook page.
-
API KEY
Generate an API key to use TuneVoyage's API.
-
STRONGER DOWNLOAD SECURITY (BETA)
MIGHT NOT WORK ON SOME BROWSERS. PLEASE, TEST FOR YOURSELF AFTER ENABLING THIS OPTION.
This will hide the download button after the gate is unlocked and force the download automatically.
This way users can not figure out and copy the direct download link of the uploaded file.
If you are using a link to an external service (like zippyshare) the button will still be visible.
-
EMBEDDABLE SMART LINKS
Allow the smart links to be embedded on other web pages.
-
PARTICLEGROUND
Enable the particleground effect and customize it. This may slow down the loading time!
-
CATALOG & PAGES SETTINGS
Select a blur level for the bakcground of pages that use this option. Show/hide categories in the catalog.
Enable/disable the social share buttons.
-
CUSTOM LOGO
Show/hide logo. Upload your own.
Maximum size: 2MB
Preffered type: .png (transparent)
Prefered maximum width: 400px
-
REPLACE SYSTEM BACKGROUND
Maximum size: 2MB
Allowed file types: .jpg, .jpeg, .gif, .png
Prefered dimensions (minimum): 1920x1080
E) Getting client ID and secret for each platform - top
In order to communicate with SoundCloud, Mixcloud, Deezer, YouTube and Spotify TuneVoyage needs an APP (client id and secret)
for each of these platforms, that you have to generate.
Each time your fans want to download something from the catalog TuneVoyage is going to ask them to give
permissions to your web APPs to connect to their SoundCloud/Spotify/YouTube/Deezer or MixCloud profile.
For each download gate there are certain actions they need to do in order to unlock the free download
(like songs, like videos, follow profiles, subscribe to channels and etc.). Those actions are called
"gate rules". Once they click the download button and authorize the connection your APP is going to
automatically fulfill the gate rules for them (they are going to follow the listed artists, profiles,
like the listed songs and etc.). TuneVoyage will unlock the download and save the statistics in the end.
You can generate the client id and secret in the developers section of each platform. After that, you only need
to copy/paste them in the settings page or during the installation of TuneVoyage. That is it!
You need to generate API KEYs only for the platforms that you want to use.
-
SPOTIFY APP - top
-
Go to https://beta.developer.spotify.com/dashboard/applications
and sign up/login.
-
In the DASHBOARD you should see a button "CREATE AN APP". Click it.
-
Write a name and description for your APP and click create. A good name would be
"Artist Name - Free Download APP", "Free Downloads by Artist Name",
"Label Name - Download Unlocker APP" or something like that, but you can put anything you desire.
Just remember, that the title should make sense and be related to your artist or label name.
Users will be asked to give permissions to your APP in order to unlock the free downloads,
so the app name will be visible to them before they authorize the connection.
You don't want them to get confused! Also write down a small description for your APP,
like "Follow to download application for Label Name's music".
Click "Next". Since we are giving away music we are NOT going to use the APP for a commercial integration. So just click on
"NO". It is also a good idea to READ THE DEVELOPERS TERMS.
Check all of the boxes and click "SUBMIT". If you want to change TuneVoyage in any way and use it COMMERCIALLY you will need
to create a new Spotify APP for commercial use.
-
You will be redirected to your APP page. Here you can see the cient ID and client secret. Just copy/paste those in TuneVoyage
(on the "SETTINGS" page or during installation).
-
It's almost done! Now all you have to do is to add the redirect URL in your APP. You can find it in "SETTINGS" or listed during installation.
Click "EDIT SETTINGS" in your APP. Add your website URL, then enter the redirect URL and don't forget to click on "ADD" before you hit the "SAVE" button.
-
Open Spotify and go to your artist/user profile to get the link.
Your link should look like this "
https://open.spotify.com/artist/10s4IScxtwz1chYgdjSork"
but you only need the part after the domain
"artist/10s4IScxtwz1chYgdjSork"
Copy/paste that part into DEFAULT PROFILES (admin/settings) for SPOTIFY.
-
YOUTUBE APP - top
-
Go to Google API Console
https://console.developers.google.com/apis.
-
Look at the top menu and click on "Select a project", then click "Create project".
-
Choose a name for your project/APP and click "create".
-
You will be redirected to a page with a list of different APIs. Search for "YouTube Data API" and click on it.
-
Now enable the YouTube Data API.
-
Click on "Credentials" in the menu on the left.
-
Now generate an API key
-
Copy the new API key in "SETTINGS" (or during isntallation).
-
In order to create a client ID you need to set a product name. Click "configure consent screen".
-
This info is going to be visible to your fans before they connect to download via YouTube. So make sure it all looks nice!
-
Create the client ID.
-
Google will now generate a client ID and APP secret.
-
Copy and paste these into TuneVoyage.
-
You also need to enter your channel URI.
-
Login to your YouTube account
-
Click on "My Channel" and look at the address bar of your browser for the channel url.
It shoud look like this:
https://www.youtube.com/channel/UC8luC9VrLAowpoPL8wFrWWw
You only need to copy the ID and paste it in the settings page or during installation.
If your link looks like this - https://www.youtube.com/user/BassOneOfficial,
this is not a valid link for TuneVoyage. You should always work with channel IDs, not custom permalinks.
To get the ID of a channel just click on any of it's videos.
Under the video you can see the channel name with the channel picture.
Click there and you will get a link, that contains the channel id.
-
DEEZER APP - top
- Register a new application here: https://developers.deezer.com/myapps/create
- Enter a name for your APP (example: Follow To Download), enter your domain and also copy/paste the redirect URL from the SETTINGS page.
-
Copy/paste the client secret and id on the settings page (or during installation).
Don't forget to also add your main artist profile.
-
MIXCLOUD APP - top
- Register a new application here: https://www.mixcloud.com/developers/
-
Copy/paste the client secret and id on the settings page (or during installation).
Don't forget to also add your main profile. Mixcloud does not require a callback URI.
-
SOUNDCLOUD APP - top
Due to the high amount of requests recently received, Soundcloud is not processing API application requests at this time.
Everyone who already have their SoundCloud API keys and have setup the SoundCloud download gates can still continue to use the feature without any problems, but new
buyers will have to wait for SoundCloud to open their API Key requests once again. Unfortunately it depends entirely on them and I can not do anything about it. If you
already have an APP you can try to contact them and see if they would change the redirect URL to the one that is listed on the "SETTINGS" page of TuneVoyage.
Taffo Velikoff
Go To Table of Contents