public WS..::.EditAudioContentResult EditAudioContentForPhone(
	string AccessKey,
	string SourceFile,
	double StartSec,
	double EndSec,
	int PhoneModelID,
	int Amplify,
	double FadeInSec,
	double FadeOutSec
)

Public Function EditAudioContentForPhone ( _
	AccessKey As String, _
	SourceFile As String, _
	StartSec As Double, _
	EndSec As Double, _
	PhoneModelID As Integer, _
	Amplify As Integer, _
	FadeInSec As Double, _
	FadeOutSec As Double _
) As WS..::.EditAudioContentResult

public function EditAudioContentForPhone(
	AccessKey : String, 
	SourceFile : String, 
	StartSec : double, 
	EndSec : double, 
	PhoneModelID : int, 
	Amplify : int, 
	FadeInSec : double, 
	FadeOutSec : double
) : WS..::.EditAudioContentResult

Parameters

AccessKey

Type: System..::.String
Security key allocated to a developer enabling access to the web service API.

SourceFile

Type: System..::.String
Internal source file name within Phone Sherpa system. Expressed as a random and unique file name without a path. Typically the output of LoadFileFromURL(...), but can be any internal SourceFile handle to an audio file.

Supported audio formats: mp3, wma, wav, aac, mp4, m4a, aif, snd, and au. Files encoded with DRM are not supported regardless of format.

StartSec

Type: System..::.Double
Time in the source audio file to begin the output clip. Expressed in seconds. Use 0.0 to start at the beginning of the source audio track. Ex: "12.6"

EndSec

Type: System..::.Double
Time in the source audio file to end the output clip. Expressed in seconds. Use 0.0 to end the clip at the end of the source audio track. Ex: "143.1"

PhoneModelID

Type: System..::.Int32
The ID of the phone model for which the audio clip is being created. The resultant audio clip will be of the best supported format for the phone model.

Amplify

Type: System..::.Int32
Amplifies the baseline volume on the output audio clip. Enumeration values for this parameter in percentage of volumne boost:
0 = 0%, 1 = 25%, 2 = 50%, 3 = 100%

FadeInSec

Type: System..::.Double
The number of seconds to apply a linear fade in from the start of the output audio clip. Use 0.0 for no fade in. Typical fade in values (if present) are 1.5 to 3.0 seconds.

FadeOutSec

Type: System..::.Double
The number of seconds to apply a linear fade out from before the end of the output audio clip. Use 0.0 for no fade out. Typical fade out values (if present) are 1.5 to 3.0 seconds.

Return Value

EditAudioContentForPhone is typically used to create ringtone audio clips for particular phone models. It generates the highest quality supported ringtone format that fits (file size-wise) on the target phone model. File size is a function of audio codec quality (bitrate) and clip duration. This function will perform a best fit of codec quality while keeping the clip duration constant, keeping the resultant file size at or below the maximum ringtone file size for the phone. This has limitations, however. If a clip is requested for 50 seconds and the phone supports 1 audio codec, it is possible to generate a ringtone that is too big to be downloaded into the handset.

Converting audio files for phone playback has several considerations. Paramount is the supported audio formats by the target phone model; handsets can only play very specific audio formats. Additionally, most phones only play particular encodings of a format. Example: many Motorola handsets play mp3 formats, but support only particular bitrate encodings. It is not sufficient to send any mp3 encoding to most Motorola handsets. The best audio codec is selected automatically by this function.

Time length of the audio clip is a 2nd consideration. Most handsets go to voice mail after 4 rings...typically 20-22 seconds after the first ring. Making ringtone clips longer than 30 seconds is a waste of file size on the handset.

Another key consideration is file size. Most phones have a maximum supported file size for audio clips used as ringtones. This varys greatly from handset to handset, resulting in clips not playing fully or clips not even able to be downloaded to the phone. File size is a function of selected codec bitrate X file length in seconds. Choosing lower bitrate (and lower quality) codecs or reducing the duration of a clip can reduce the output file size. This calculation is done automatically by this function.

Amplification is needed only in cases where a handset is known to have poor playback abilities through its external speaker. Amplifying output files 50% or more typcialy results in poor audio quality, as any "loud" parts of the audio are "clipped" or chopped out of the audio waveform. The output file maybe loud but it may also be unrecognizable.

The ConvertedFile in the result object can be used in any function that takes a SourceFile parameter, such as the SendContentToPhone(...) function.

Below is an example of how to use this function:

CopyVB.NET

Public Sub EditAndDeliverRingtone(ByVal UserPhoneInfo As PhoneSherpa.Services.UserPhoneInformation, ByVal SourceFile As String, ByVal FriendlyFileName As String, ByVal StartSec As Double, ByVal EndSec As Double, ByVal FadeInSec As Double, ByVal FadeOutSec As Double)
   Dim SherpaService As New PhoneSherpa.Services.WS

   'Take the editor parameters and clip/convert the source file for the user's phone model.  
   Dim RingtoneEdit_Response As New PhoneSherpa.Services.EditAudioContentResult

   RingtoneEdit_Response = SherpaService.EditAudioContentForPhone("My_WSAccessKey", SourceFile, StartSec, EndSec, UserPhoneInfo.PhoneModelId, 0, FadeInSec, FadeOutSec)

   'Check the response to ensure the call worked
   If RingtoneEdit_Response.Result.ErrorCode = 0 Then
       'Bill the user or take some other action within the host application code
        '[host actions here]

        'Deliver the converted ringtone clip the the user's phone
        'This assumes that host applicatoin has presented a UI for selecting phone model or is pulling this information from its 
        'own account system
        Dim SendToPhone_Response As New PhoneSherpa.Services.SendContentToPhoneResult

        SendToPhone_Response = SherpaService.SendContentToPhone("My_WSAccessKey", UserPhoneInfo, RingtoneEdit_Response.ConvertedFile, FriendlyFileName)

        If SendToPhone_Response.Result.ErrorCode = 0 Then
            'ringtone delivery succeeded, redirect user to a success page and display ringtone install instructions
            '...
        Else
            'error - the send ringtone to phone call failed, redirect to an error handler
        End If
    Else
        'error - the ringtone edit call failed, redirect to an error handler
    End If
End Sub