Package: rev-ai
Rev AI Python SDKDocumentationSee theAPI docsfor more information about the API and
more python examples.InstallationYou don't need this source code unless you want to modify the package. If you just
want to use the package, just run:pip install --upgrade rev_aiInstall from source with:python setup.py installRequirementsPython 3.8+UsageAll you need to get started is your Access Token, which can be generated on
yourAccessToken Settings Page. Create a client with the
generated Access Token:fromrev_aiimportapiclient# create your clientclient=apiclient.RevAiAPIClient("ACCESS TOKEN")Sending a fileOnce you've set up your client with your Access Token sending a file is easy!# you can send a local filejob=client.submit_job_local_file("FILE PATH")# or send a link to the file you want transcribedjob=client.submit_job_url("https://example.com/file-to-transcribe.mp3")jobwill contain all the information normally found in a successful response from ourSubmit Jobendpoint.If you want to get fancy, both submit job methods takemetadata,notification_config,skip_diarization,skip_punctuation,speaker_channels_count,custom_vocabularies,filter_profanity,remove_disfluencies,delete_after_seconds,language,
andcustom_vocabulary_idas optional parameters.The url submission option also supports authentication headers by using thesource_configoption.You can request transcript summary.# submitting a human transcription jobsjob=client.submit_job_url("https://example.com/file-to-transcribe.mp3",language='en',summarization_config=SummarizationOptions(formatting_type=SummarizationFormattingOptions.BULLETS))You can request transcript translation into up to five languages.job=client.submit_job_url("https://example.com/file-to-transcribe.mp3",language='en',translation_config=TranslationOptions(target_languages:[TranslationLanguageOptions("es",TranslationModel.PREMIUM),TranslationLanguageOptions("de")]));All options are described in the request body of theSubmit Jobendpoint.Human TranscriptionIf you want transcription to be performed by a human, both methods allow you to submit human transcription jobs
usingtranscriber=humanwithverbatim,rush,segments_to_transcribeandtest_modeas optional parameters.
Check out our documentation forHuman Transcriptionfor more details.# submitting a human transcription jobsjob=client.submit_job_url("https://example.com/file-to-transcribe.mp3",transcriber='human',verbatim=False,rush=False,test_mode=Truesegments_to_transcribe=[{start:2.0,end:4.5}])Checking your file's statusYou can check the status of your transcription job using itsidjob_details=client.get_job_details(job.id)job_detailswill contain all information normally found in a successful response from
ourGet JobendpointChecking multiple filesYou can retrieve a list of transcription jobs with optional parametersjobs=client.get_list_of_jobs()# limit amount of retrieved jobsjobs=client.get_list_of_jobs(limits=3)# get jobs starting after a certain job idjobs=client.get_list_of_jobs(starting_after='Umx5c6F7pH7r')jobswill contain a list of job details having all information normally found in a successful response
from ourGet List of JobsendpointDeleting a jobYou can delete a transcription job using itsidclient.delete_job(job.id)All data related to the job, such as input media and transcript, will be permanently deleted.
A job can only by deleted once it's completed (either with success or failure).Getting your transcriptOnce your file is transcribed, you can get your transcript in a few different forms:# as texttranscript_text=client.get_transcript_text(job.id)# as jsontranscript_json=client.get_transcript_json(job.id)# or as a python objecttranscript_object=client.get_transcript_object(job.id)# or if you requested transcript translation(s)transcript_object=client.get_translated_transcript_object(job.id,'es')Both the json and object forms contain all the formation outlined in the response
of theGet Transcriptendpoint
when using the json response schema. While the text output is a string containing
just the text of your transcriptGetting transcript summaryIf you requested transcript summary, you can retrieve it as plain text or structured object:# as textsummary=client.get_transcript_summary_text(job.id)# as jsonsummary=client.get_transcript_summary_json(job.id)# or as a python objectsummary=client.get_transcript_summary_object(job.id)Getting captions outputYou can also get captions output from the SDK. We offer both SRT and VTT caption formats.
If you submitted your job as speaker channel audio then you must also provide achannel_idto be captioned:captions=client.get_captions(job.id,content_type=CaptionType.SRT,channel_id=None)# or if you requested transcript translation(s)captions=client.get_translated_captions(job.id,'es')Streamed outputsAny output format can be retrieved as a stream. In these cases we return the raw http response to you. The output can be retrieved viaresponse.content,response.iter_lines()orresponse.iter_content().text_stream=client.get_transcript_text_as_stream(job.id)json_stream=client.get_transcript_json_as_stream(job.id)captions_stream=client.get_captions_as_stream(job.id)Streaming audioIn order to stream audio, you will need to setup a streaming client and a media configuration for the audio you will be sending.fromrev_ai.streamingclientimportRevAiStreamingClientfromrev_ai.modelsimportMediaConfig#on_error(error)#on_close(code, reason)#on_connected(id)config=MediaConfig()streaming_client=RevAiStreamingClient("ACCESS TOKEN",config,on_error=ERRORFUNC,on_close=CLOSEFUNC,on_connected=CONNECTEDFUNC)on_error,on_close, andon_connectedare optional parameters that are functions to be called when the websocket errors, closes, and connects respectively. The defaulton_errorraises the error,on_closeprints out the code and reason for closing, andon_connectedprints out the job ID.
If passing in custom functions, make sure you provide the right parameters. See the sample code for the parameters.Once you have a streaming client setup with aMediaConfigand access token, you can obtain a transcription generator of your audio. You can also use a custom vocabulary with your streaming job by supplying the optionalcustom_vocabulary_idwhen starting a connection!More optional parameters can be supplied when starting a connection, these aremetadata,filter_profanity,remove_disfluencies,delete_after_seconds, anddetailed_partials. For a description of these optional parameters look at ourstreaming documentation.response_generator=streaming_client.start(AUDIO_GENERATOR,custom_vocabulary_id="CUSTOM VOCAB ID")response_generatoris a generator object that yields the transcription results of the audio including partial and final transcriptions. Thestartmethod creates a thread sending audio pieces from theAUDIO_GENERATORto our
[streaming] endpoint.If you want to end the connection early, you can!streaming_client.end()Otherwise, the connection will end when the server obtains an "EOS" message.Submitting custom vocabulariesIn addition to passing custom vocabularies as parameters in the async API client, you can create and submit your custom vocabularies independently and directly to the custom vocabularies API, as well as check on their progress.Primarily, the custom vocabularies client allows you to submit and preprocess vocabularies for use with the streaming client, in order to have streaming jobs with custom vocabularies!In this example you see how to construct custom vocabulary objects, submit them to the API, and check on their progress and metadata!fromrev_aiimportcustom_vocabularies_clientfromrev_ai.modelsimportCustomVocabulary# Create a clientclient=custom_vocabularies_client.RevAiCustomVocabulariesClient("ACCESS TOKEN")# Construct a CustomVocabulary object using your desired phrasescustom_vocabulary=CustomVocabulary(["Patrick Henry Winston","Robert C Berwick","Noam Chomsky"])# Submit the CustomVocabularycustom_vocabularies_job=client.submit_custom_vocabularies([custom_vocabulary])# View the job's progressjob_state=client.get_custom_vocabularies_information(custom_vocabularies_job['id'])# Get list of previously submitted custom vocabulariescustom_vocabularies_jobs=client.get_list_of_custom_vocabularies()# Delete the CustomVocabularyclient.delete_custom_vocabulary(custom_vocabularies_job['id'])For more details, check out the custom vocabularies example in ourexamples.For Rev AI Python SDK DevelopersRemember in your development to follow the PEP8 style guide. Your code editor likely has Python PEP8 linting packages which can assist you in your development.Local testing instructionsPrequisites: virtualenv, toxTo test locally use the following commands from the repo rootvirtualenv ./sdk-test
. ./sdk-test/bin/activate
toxThis will locally run the test suite, and saves significant dev time over
waiting for the CI tool to pick it up.=======
History0.0.0 (2018-09-28)Initial alpha release2.1.0Revamped official release2.1.1File upload bug fixes2.2.1Better Documentation2.2.2Fix pypi readme formatting2.3.0Add get_list_of_jobs2.4.0Add support for custom vocabularies2.5.0Add examplesImprove error handlingAdd streaming client2.6.0Support skip_punctuationSupport .vtt captions outputSupport speaker channel jobs2.6.1Add metadata to streaming client2.7.0Add custom vocabularies to streaming client2.7.1Use v1 of the streaming apiAdd custom vocabulary to async exampleAdd filter_profanity to async and streaming clients, examples, and documentationAdd remove_disfluencies to async client2.11.0Add language selection option for multi-lingual ASR jobs to async client2.12.0Add custom_vocabulary_id to async client2.13.0Add detailed_partials to streaming clientSwitch to Github Actions for automated testing2.14.0Add transcriber to async clientAdd verbatim, rush, segments_to_transcribe, test_mode to async client for human transcriptionAdd start_ts and transcriber to streaming client2.15.0Add topic extraction clientAdd speaker_names to async client for human transcription2.16.0Add sentiment analysis clientAdd source_config and notification_config job options to support customer provided urls with authentication headersDeprecate media_url option, replace with source_configDeprecate callback_url option, replace with notification_config2.17.0Add language to the streaming client2.18.0Add atmospherics and speaker_count supportDeprecated support for Python versions up to 3.82.19.0Add async translation and summarization