Phone Sherpa - Ringtone Maker | Sell Ringtones | Make MP3 Ringtones

SDK Overview: Why Use This SDK?; What Can Be Built; SDK Contents; Download
Key Concepts: Development Approach; API Access; Merchant Accounts; File Upload and Flow
Documentation: API Reference; Ringtone Editor; API WSDL; API Test Harness; SOAP Definitions
Sample Code: Custom Ringtone Store; Editor Initializing

Ringtone Editor Flash Client

Overview

The Flash ringtone editor client provides an end user experience for cutting audio clips from source audio files. When used in combination with the Phone Sherpa web service API, rich ringtone making applications can be built. The audio editing client has the following abilities:

- Customized color scheme to fit host web environment
- Browsing source audio files on user's computer
- Uploading the files to Phone Sherpa servers
- Generating wave form images of source audio
- Fine grain selection of the start and stop times for an audio clip
- Realtime playback of selected audio clip
- Transfer back into host web site post editing OR
- Launching Flash billing component to charge and deliver ringtone to end user

How and When To Use This Component

The Flash ringtone editor client is not required to build custom ringtone solutions. That said, it provides a flexible and complete audio editing experience greatly accelerating the time to market for custom ringtone solutions built with this SDK.

The component supports several ways to load the source audio files, represented by the finmode parameter. Changing finmode enables scenarios such as allowing the end user to upload thier own source files for true UGC ringtones or loading source files from a URL specified by the host for "mobilizing" existing full track audio libraries.

The editor client has the ability to bill and delivery the mobile content directly to the user without further interaction from the host environment. It also has the ability to transition back into the host web side after performing just the editing step, allowing the host to bill, deliver, track, archive content...basically anything they want to do with the clipped ringtone file. Phone Sherpa's web services provide methods that can be assembed into a wide variety of host solutions. The foutmode parameter determines the Flash client behavior post editing.

Ringtone Editor UI Screenshots

User File Upload

Editing Audio Clip

Billing and Delivery

Embed Tag Parameters

The following are the supported embed tag parameters for the Flash ringtone editor client component. * indicates required parameters. Some parameters are requried pending the selected finmode and foutmode values.

Flash Ringtone Editor Embed Tag Parameters
Parameter	Description and Values	Type
fpid*	A registered Phone Sherpa merchant ID. Go here to signup for a merchant account. Email bizdev@phonesherpa.com to enable your merchant account to use the ringtone editor component.	string
finmode*	The file source that the editor loads from. See finmode table for supported values.	integer
foutmode*	What the editor does after editing the file. See foutmode table for supported values.	integer
flang	The Phone Sherpa country ID to run under, affects price display and future string localization, defaults to 226 (USA)	integer
fguid	A merchant asset identifier for Phone Sherpa hosted files used in finmode 3. These are files uploaded into a merchant account and managed by Phone Sherpa. This parameter is not often used.	string
fsl_url	Fully qualified URL for a source audio file used in finmode 4 Ex: "http://www.mysite.com/source/myband_song_1.mp3"	string
ftransactionid	Passthrough value typically set by partners foutmode 0, helps synch transactions across editing step. Ex: "123-1234"	string
feditfilename	Random file name from the web service call PhoneSherpa.Services.WS.LoadFileFromURL(...), allows secure transfer of source files from host environment to Phone Sherpa servers. The source file URL is not passed to the client browser. Ex: "xqr3mgp.qkr.mp3"	string
ffriendlyfilename	The user friendly file name of a file sideloaded from a URL, typically different than the source URL file name. Ex: "myband%20track.mp3"	string
ftransferurl	The fully qualified URL that the editor transfers back to in foutmode 0. See Transfer Page Parameters to see what is passed to the transfer page. Ex: "http://www.mysite.com/edit_transfer.php"	string
fsuccessurl	the fully qualified URL that the billing component redirects the browser to if it is doing billing and the user completes the transaction. Ex: "http://www.mysite.com/transaction_success.php"	string
fcontenttitle	For file purchases in foutmode 3 this title is displayed to the user in billing, if unspecified a default description is displayed. Ex: "A%20Cool%20Song"	string
fusagecharge	The amount that should be charged to the user for use of the editor for foutmode 3. This is an enumerated value (see below for values)	integer
fcolorlightbg	Editor background color in RGB Hex. Default color if not specified.	string
fcolordarkbg	Editor border color in RGB Hex. Default color if not specified.	string
fcolorbuttonbg	Button face color in RGB Hex. Default color if not specified.	string
fcolorbuttonfg	Button text color in RGB Hex. Default color if not specified.	string
fcolorlighttext	Editor border text color in RGB Hex. Default color if not specified.	string
fcolordarktext	Editor background text color in RGB Hex. Default color if not specified.	string

Modes and Enumeration Values

The audio editor has "inmodes" and "outmodes" controlling the file load and post editing behavior of the component. Depending on the selected inmode, only certian outmodes are enabled and certian additional parameters are required in the Flash embed tag.

Supported finmode Values
finmode	foutmode	Required Additional Parameters
0 - User file	0 - Return to host 3 - Bill single item	[none]
1 - Standalone Ringtone Maker	1 - Bill user credits	[none]
3 - Merchant Asset	0 - Return to host 2 - Bill asset settings	fguid
4 - File from URL	0 - Return to host 3 - Bill single item	fsl_url
5 - File from Pre-loaded URL	0 - Return to host 3 - Bill single item	feditfilename

Supported foutmode Values
foutmode	Description	Required Parameters
0	No billing or delivery, transfer back to host specified URL	ftransferurl
1	Bill user credits against a Phone Sherpa account	[none]
2	Bill user money based on merchant asset properties	fguid
3	Bill user money for single item purchase	ffriendlyfilename, fcontenttitle, fusagecharge

Supported fusagecharge Values
fusagecharge	Value in USD
1	Free, requires special arrangement with Phone Sherpa to enable this value
2	$0.99
3	$1.99
4	$4.99
5	$9.99
6	1 Phone Sherpa Credit (for use only with finmode 1)
7	2 Phone Sherpa Credits (for use only with finmode 1)
8	$2.49
9	$2.99
10	$3.50
11	$3.99

Transfer Page Parameters

The foutmode 0 causes the editor to do a Javascript document redirect inside the client browser to the URL specifed by ftranferurl. This happens when the user presses the "Continue" button. In this mode, the editor is used strictly for preparation of the clipped ringtone, not for billing or delivery.

A series of parameters are passed to the ftransferurl page via the querystring. Typically, the host website will read the querystring parameters and then redirect the client browser to a new page based on the hosts application logic. This method enables the end user experience to appear seemless despite flow control handoff between Phone Sherpa's Flash client and the host web site.

The parameters passed to the transfer page via querystring are listed below:

Transfer Page Querystring Parameters
Parameter	Description and Values	Type
Request_Type	Internal use only, can be ignored.	integer
Internal_Source_File	The source file that was being edited inside the editor client. This is not the clipped, file. It is the source file in which the clipped file can be produced from. This value is a random file name and unique within the Phone Sherpa system.	string
Asset_GUID	A merchant asset identifier for Phone Sherpa hosted files used in finmode 3. These are files uploaded into a merchant account and managed by Phone Sherpa. This parameter is not often used.	string
Start_Sec	The time point within the source file the user selected to start the audio clip.	double
End_Sec	The time point within the source file the user selected to end the audio clip.	double
Fade_In_Sec	Time to fade in the clip from 0% to 100% volume at the start of the clip. The fade is linear. Fade_In_Sec 0 means no fade in.	double
Fade_Out_Sec	Time to fade out the clip from 100% to 0% volume at the end of the clip. The fade is linear. Fade_Out_Sec 0 means no fade out.	double
Transaction_ID	Passthrough value set by the host, helps synch transactions across editing step. This can be any value you need.	string
Friendly_File_Name	The user friendly file name of a file, typically different than the source URL file name. Ex: "myband%20track.mp3"	string

Embed Tag Syntax Example


	                               < object type="application/x-shockwave-flash" 
	                               data="http://www.phonesherpa.com/flash/editor.swf?
	                               fpid=phonesherpa&flang=226&fcolorlightbg=FFFFFF&fcolordarkbg=7D7D7D
	                               &fcolorbuttonbg=0586FF&fcolorbuttonfg=FFFFFF&fcolorlighttext=000000
	                               &fcolordarktext=000000&fcontenttitle=NewRingtone&fusagecharge=3&finmode=0
	                               &foutmode=3" height="250" width="450">