googleLanguageR

Description

This package contains functions for analysing language through the Google Cloud Machine Learning APIs

Details

For examples and documentation see the vignettes and the website:

https://github.com/ropensci/googleLanguageR

Author(s)

Maintainer: Cheryl Isabella cheryl.academic@gmail.com

Authors:

• Mark Edmondson r@sunholo.com

Other contributors:

• Aleksander Dietrichson dietrichson@gmail.com [contributor]

• John Muschelli muschellij2@gmail.com [contributor]

• Neal Richardson neal.p.richardson@gmail.com (Neal reviewed the package for ropensci) [reviewer]

• Julia Gustavsen j.gustavsen@gmail.com (Julia reviewed the package for ropensci) [reviewer]

See Also

https://cloud.google.com/products/machine-learning

googleLanguageR: Interface to Google Cloud NLP, Translation, and Speech APIs

A package for interacting with Google Cloud's language APIs from R.

Determine API endpoint version

Description

Used to specify the API endpoint: GitHub beta versions or CRAN stable.

Usage

get_version(api = c("nlp", "tts", "speech", "trans"))

Arguments

Value

Character string of API version

Authenticate with Google Language API services

Description

Authenticate with Google Language API services

Usage

gl_auth(json_file)

gl_auto_auth(...)

Arguments

Details

This function authenticates with Google Cloud's language APIs. By default, it uses the JSON file specified in json_file. Alternatively, you can set the file path in the environment variable GL_AUTH to auto-authenticate when loading the package.

Examples

## Not run: 
library(googleLanguageR)
gl_auth("path/to/json_file.json")

## End(Not run)
## Not run: 
library(googleLanguageR)
gl_auto_auth()
gl_auto_auth(environment_var = "GAR_AUTH_FILE")

## End(Not run)

Perform Natural Language Analysis

Description

Analyse text for entities, sentiment, syntax and classification using the Google Natural Language API.

Usage

gl_nlp(
  string,
  nlp_type = c("annotateText", "analyzeEntities", "analyzeSentiment", "analyzeSyntax",
    "analyzeEntitySentiment", "classifyText"),
  type = c("PLAIN_TEXT", "HTML"),
  language = c("en", "zh", "zh-Hant", "fr", "de", "it", "ja", "ko", "pt", "es"),
  encodingType = c("UTF8", "UTF16", "UTF32", "NONE")
)

Arguments

Details

Encoding type can usually be left at the default UTF8. Further details on encoding types.

Current language support is listed here.

Value

A list containing the requested components as specified by nlp_type:

See Also

https://cloud.google.com/natural-language/docs/reference/rest/v1/documents

Examples

## Not run: 
library(googleLanguageR)

text <- "To administer medicine to animals is frequently difficult, yet sometimes necessary."
nlp <- gl_nlp(text)

nlp$sentences
nlp$tokens
nlp$entities
nlp$documentSentiment

# Vectorised input
texts <- c("The cat sat on the mat.", "Oh no, it did not, you fool!")
nlp_results <- gl_nlp(texts)

## End(Not run)

Call Google Speech API

Description

Turn audio into text

Usage

gl_speech(
  audio_source,
  encoding = c("LINEAR16", "FLAC", "MULAW", "AMR", "AMR_WB", "OGG_OPUS",
    "SPEEX_WITH_HEADER_BYTE"),
  sampleRateHertz = NULL,
  languageCode = "en-US",
  maxAlternatives = 1L,
  profanityFilter = FALSE,
  speechContexts = NULL,
  asynch = FALSE,
  customConfig = NULL
)

Arguments

Details

Google Cloud Speech API enables developers to convert audio to text by applying powerful neural network models in an easy to use API. The API recognizes over 80 languages and variants, to support your global user base. You can transcribe the text of users dictating to an application’s microphone, enable command-and-control through voice, or transcribe audio files, among many other use cases. Recognize audio uploaded in the request, and integrate with your audio storage on Google Cloud Storage, by using the same technology Google uses to power its own products.

Value

A list of two tibbles: $transcript, a tibble of the transcript with a confidence; $timings, a tibble that contains startTime, endTime per word. If maxAlternatives is greater than 1, then the transcript will return near-duplicate rows with other interpretations of the text. If asynch is TRUE, then an operation you will need to pass to gl_speech_op to get the finished result.

AudioEncoding

Audio encoding of the data sent in the audio message. All encodings support only 1 channel (mono) audio. Only FLAC and WAV include a header that describes the bytes of audio that follow the header. The other encodings are raw audio bytes with no header. For best results, the audio source should be captured and transmitted using a lossless encoding (FLAC or LINEAR16). Recognition accuracy may be reduced if lossy codecs, which include the other codecs listed in this section, are used to capture or transmit the audio, particularly if background noise is present.

Read more on audio encodings here https://cloud.google.com/speech-to-text/docs/encoding

WordInfo

startTime - Time offset relative to the beginning of the audio, and corresponding to the start of the spoken word.

endTime - Time offset relative to the beginning of the audio, and corresponding to the end of the spoken word.

word - The word corresponding to this set of information.

See Also

https://cloud.google.com/speech/reference/rest/v1/speech/recognize

Examples

## Not run: 

test_audio <- system.file("woman1_wb.wav", package = "googleLanguageR")
result <- gl_speech(test_audio)

result$transcript
result$timings

result2 <- gl_speech(test_audio, maxAlternatives = 2L)
result2$transcript

result_brit <- gl_speech(test_audio, languageCode = "en-GB")


## make an asynchronous API request (mandatory for sound files over 60 seconds)
asynch <- gl_speech(test_audio, asynch = TRUE)

## Send to gl_speech_op() for status or finished result
gl_speech_op(asynch)

## Upload to GCS bucket for long files > 60 seconds
test_gcs <- "gs://mark-edmondson-public-files/googleLanguageR/a-dream-mono.wav"
gcs <- gl_speech(test_gcs, sampleRateHertz = 44100L, asynch = TRUE)
gl_speech_op(gcs)

## Use a custom configuration
my_config <- list(encoding = "LINEAR16",
                  diarizationConfig = list(
                    enableSpeakerDiarization = TRUE,
                    minSpeakerCount = 2,
                    maxSpeakCount = 3
                    ))

# languageCode is required, so will be added if not in your custom config
gl_speech(my_audio, languageCode = "en-US", customConfig = my_config)


## End(Not run)

Get a speech operation

Description

For asynchronous calls of audio over 60 seconds, this returns the finished job

Usage

gl_speech_op(operation = .Last.value)

Arguments

Value

If the operation is still running, another operation object. If done, the result as per gl_speech

See Also

gl_speech

Examples

## Not run: 

test_audio <- system.file("woman1_wb.wav", package = "googleLanguageR")

## make an asynchronous API request (mandatory for sound files over 60 seconds)
asynch <- gl_speech(test_audio, asynch = TRUE)

## Send to gl_speech_op() for status or finished result
gl_speech_op(asynch)


## End(Not run)

Perform text to speech

Description

Synthesizes speech synchronously: receive results after all text input has been processed.

Usage

gl_talk(
  input,
  output = "output.wav",
  languageCode = "en",
  gender = c("SSML_VOICE_GENDER_UNSPECIFIED", "MALE", "FEMALE", "NEUTRAL"),
  name = NULL,
  audioEncoding = c("LINEAR16", "MP3", "OGG_OPUS"),
  speakingRate = 1,
  pitch = 0,
  volumeGainDb = 0,
  sampleRateHertz = NULL,
  inputType = c("text", "ssml"),
  effectsProfileIds = NULL,
  forceLanguageCode = FALSE
)

Arguments

Details

Requires the Cloud Text-To-Speech API to be activated for your Google Cloud project.

Supported voices are here https://cloud.google.com/text-to-speech/docs/voices and can be imported into R via gl_talk_languages

To play the audio in code via a browser see gl_talk_player

To use Speech Synthesis Markup Language (SSML) select inputType=ssml - more details on using this to insert pauses, sounds and breaks in your audio can be found here: https://cloud.google.com/text-to-speech/docs/ssml

To use audio profiles, supply a character vector of the available audio profiles listed here: https://cloud.google.com/text-to-speech/docs/audio-profiles - the audio profiles are applied in the order given. For instance effectsProfileIds="wearable-class-device" will optimise output for smart watches, effectsProfileIds=c("wearable-class-device","telephony-class-application") will apply sound filters optimised for smart watches, then telephonic devices.

Value

The file output name you supplied as output

See Also

https://cloud.google.com/text-to-speech/docs/

Examples

## Not run: 
library(magrittr)
gl_talk("The rain in spain falls mainly in the plain",
        output = "output.wav")

gl_talk("Testing my new audio player") %>% gl_talk_player()

# using SSML
gl_talk('<speak>The <say-as interpret-as=\"characters\">SSML</say-as>
  standard <break time=\"1s\"/>is defined by the
  <sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>',
  inputType =  "ssml")

# using effects profiles
gl_talk("This sounds great on headphones",
        effectsProfileIds = "headphone-class-device")


## End(Not run)

Get a list of voices available for text to speech

Description

Returns a list of voices supported for synthesis.

Usage

gl_talk_languages(languageCode = NULL)

Arguments

Play audio in a browser

Description

This uses HTML5 audio tags to play audio in your browser

Usage

gl_talk_player(audio = "output.wav", html = "player.html")

Arguments

Details

A platform neutral way to play audio is not easy, so this uses your browser to play it instead.

Examples

## Not run: 

gl_talk("Testing my new audio player") %>% gl_talk_player()


## End(Not run)

Speak in Shiny module (server)

Description

Call via shiny::callModule(gl_talk_shiny, "your_id")

Usage

gl_talk_shiny(
  input,
  output,
  session,
  transcript,
  ...,
  autoplay = TRUE,
  controls = TRUE,
  loop = FALSE,
  keep_wav = FALSE
)

Arguments

Speak in Shiny module (ui)

Description

Speak in Shiny module (ui)

Usage

gl_talk_shinyUI(id)

Arguments

Details

Shiny Module for use with gl_talk_shiny.

Translate the language of text within a request

Description

Translate character vectors via the Google Translate API.

Usage

gl_translate(
  t_string,
  target = "en",
  format = c("text", "html"),
  source = "",
  model = c("nmt", "base")
)

Arguments

Details

You can translate a vector of strings; if too many for one call, it will be broken up into one API call per element. The API charges per character translated, so splitting does not change cost but may take longer.

If translating HTML, set format = "html". Consider removing anything not needed to be translated first, such as JavaScript or CSS.

API limits: characters per day, characters per 100 seconds, and API requests per 100 seconds. These can be configured in the API manager: https://console.developers.google.com/apis/api/translate.googleapis.com/quotas

Value

A tibble of translatedText, detectedSourceLanguage, and text of length equal to the vector of text you passed in

See Also

https://cloud.google.com/translate/docs/reference/translate

Other translations: gl_translate_detect(), gl_translate_document(), gl_translate_languages()

Detect the language of text within a request

Description

Detect the language of text within a request

Usage

gl_translate_detect(string)

Arguments

Details

Consider using library(cld2) and cld2::detect_language instead for offline detection, since that is free and does not require an API call.

gl_translate also returns a detection of the language, so you could optionally use that in one step.

Value

A tibble of the detected languages with columns confidence, isReliable, language, and text, of length equal to the vector of text you passed in.

See Also

https://cloud.google.com/translate/docs/reference/detect

Other translations: gl_translate(), gl_translate_document(), gl_translate_languages()

Examples

## Not run: 
gl_translate_detect("katten sidder på måtten")

## End(Not run)

Translate a document via the Google Translate API

Description

Translate a document via the Google Translate API

Usage

gl_translate_document(
  d_path,
  target = "es-ES",
  output_path = "out.pdf",
  format = c("pdf"),
  source = "en-UK",
  model = c("nmt", "base"),
  location = "global"
)

Arguments

Value

The full path of the translated document

See Also

Other translations: gl_translate(), gl_translate_detect(), gl_translate_languages()

Examples

## Not run: 
gl_translate_document(
  system.file(package = "googleLanguageR", "test-doc.pdf"),
  target = "no"
)

## End(Not run)

Lists languages from Google Translate API

Description

Returns a list of supported languages for translation.

Usage

gl_translate_languages(target = "en")

Arguments

Details

Supported language codes generally consist of their ISO 639-1 identifiers (e.g., 'en', 'ja'). In certain cases, BCP-47 codes including language + region identifiers are returned (e.g., 'zh-TW', 'zh-CH').

Value

A tibble of supported languages

See Also

https://cloud.google.com/translate/docs/reference/languages

Other translations: gl_translate(), gl_translate_detect(), gl_translate_document()

Examples

## Not run: 
gl_translate_languages()
gl_translate_languages("da")

## End(Not run)

A helper function that tests whether an object is either NULL _or_ a list of NULLs

Description

A helper function that tests whether an object is either NULL _or_ a list of NULLs

Usage

is.NullOb(x)

Test if a string is a Google Cloud Storage URI

Description

Test if a string is a Google Cloud Storage URI

Usage

is.gcs(x)

Arguments

Value

Logical

Safe cbind that removes data.frames with no rows

Description

Safe cbind that removes data.frames with no rows

Usage

my_cbind(...)

Custom messaging function for package

Description

Custom messaging function for package

Usage

my_message(..., level = 1)

Arguments

Recursively remove NULL objects from a list

Description

Recursively remove NULL objects from a list

Usage

rmNullObs(x)