---
title: "Quickstart: geniusR"
author: "Josiah Parry"
date: "2/12/2018"
---
# Overview
This package was created to provide an easy method to access lyrics as text data using the website [Genius](genius.com).
## Installation
This package must be installed from GitHub.
```{r, eval = F}
devtools::install_github("josiahparry/geniusR")
```
Load the package:
```{r}
library(geniusR)
library(tidyverse) # For manipulation
```
# Getting Lyrics
## Whole Albums
`genius_album()` allows you to download the lyrics for an entire album in a `tidy` format. There are two arguments `artists` and `album`. Supply the quoted name of artist and the album (if it gives you issues check that you have the album name and artists as specified on [Genius](https://genius.com)).
This returns a tidy data frame with three columns:
- `title`: track name
- `track_n`: track number
- `text`: lyrics
```{r}
emotions_math <- genius_album(artist = "Margaret Glaspy", album = "Emotions and Math")
emotions_math
```
## Multiple Albums
If you wish to download multiple albums from multiple artists, try and keep it tidy and avoid binding rows if you can. We can achieve this in a tidy workflow by creating a tibble with two columns: `artist` and `album` where each row is an artist and their album. We can then iterate over those columns with `purrr:map2()`.
In this example I will extract 3 albums from Kendrick Lamar and Sara Bareilles (two of my favotire musicians). The first step is to create the tibble with artists and album titles.
```{r}
albums <- tibble(
artist = c(
rep("Kendrick Lamar", 3),
rep("Sara Bareilles", 3)
),
album = c(
"Section 80", "Good Kid, M.A.A.D City", "DAMN.",
"The Blessed Unrest", "Kaleidoscope Heart", "Little Voice"
)
)
albums
```
No we can iterate over each row using the `map2` function. This allows us to feed each value from the `artist` and `album` columns to the `genius_album()` function. Utilizing a `map` call within a `dplyr::mutate()` function creates a list column where each value is a `tibble` with the data frame from `genius_album()`. We will later unnest this.
```{r}
## We will have an additional artist column that will have to be dropped
album_lyrics <- albums %>%
mutate(tracks = map2(artist, album, genius_album))
album_lyrics
```
Now when you view this you will see that each value within the `tracks` column is `<tibble>`. This means that that value is infact another `tibble`. We expand this using `tidyr::unnest()`.
```{r}
# Unnest the lyrics to expand
lyrics <- album_lyrics %>%
unnest(tracks) %>% # Expanding the lyrics
arrange(desc(artist)) # Arranging by artist name
head(lyrics)
```
## Song Lyrics
### `genius_lyrics()`
If you want only a single song, you can use `genius_lyrics()`. Supply an artist and a song title as character strings, and voila.
```{r}
memory_street <- genius_lyrics(artist = "Margaret Glaspy", song = "Memory Street")
memory_street
```
This returns a `tibble` with three columns `title`, `text`, and `line`. However, you can specifiy additional arguments to control the amount of information to be returned using the `info` argument.
- `info = "title"` (default): Return the lyrics, line number, and song title.
- `info = "simple"`: Return just the lyrics and line number.
- `info = "artist"`: Return the lyrics, line number, and artist.
- `info = "all"`: Return lyrics, line number, song title, artist.
## Tracklists
`genius_tracklist()`, given an `artist` and an `album` will return a barebones `tibble` with the track title, track number, and the url to the lyrics.
```{r}
genius_tracklist(artist = "Basement", album = "Colourmeinkindness")
```
## Nitty Gritty
`genius_lyrics()` generates a url to Genius which is fed to `genius_url()`, the function that does the heavy lifting of actually fetching lyrics.
I have not figured out all of the patterns that are used for generating the Genius.com urls, so errors are bound to happen. If `genius_lyrics()` returns an error. Try utilizing `genius_tracklist()` and `genius_url()` together to get the song lyrics.
For example, say "(No One Knows Me) Like the Piano" by _Sampha_ wasn't working in a standard `genius_lyrics()` call.
```{r, eval = FALSE}
piano <- genius_lyrics("Sampha", "(No One Knows Me) Like the Piano")
```
We could grab the tracklist for the album _Process_ which the song is from. We could then isolate the url for _(No One Knows Me) Like the Piano_ and feed that into `genius_url().
```{r}
# Get the tracklist for
process <- genius_tracklist("Sampha", "Process")
# Filter down to find the individual song
piano_info <- process %>%
filter(title == "(No One Knows Me) Like the Piano")
# Filter song using string detection
# process %>%
# filter(stringr::str_detect(title, coll("Like the piano", ignore_case = TRUE)))
piano_url <- piano_info$track_url
```
Now that we have the url, feed it into `genius_url()`.
```{r}
genius_url(piano_url, info = "simple")
```
___________
# On the Internals
## Generative functions
This package works almost entirely on pattern detection. The urls from _Genius_ are (mostly) easily reproducible (shout out to [Angela Li](https://twitter.com/CivicAngela) for pointing this out).
The two functions that generate urls are `gen_song_url()` and `gen_album_url()`. To see how the functions work, try feeding an artist and song title to `gen_song_url()` and an artist and album title to `gen_album_url()`.
```{r}
gen_song_url("Laura Marling", "Soothing")
```
```{r}
gen_album_url("Daniel Caesar", "Freudian")
```
`genius_lyrics()` calls `gen_song_url()` and feeds the output to `genius_url()` which preforms the scraping.
Getting lyrics for albums is slightly more involved. It first calls `genius_tracklist()` which first calls `gen_album_url()` then using the handy package `rvest` scrapes the song titles, track numbers, and song lyric urls. Next, the song urls from the output are iterated over and fed to `genius_url()`.
To make this more clear, take a look inside of `genius_album()`
```{r}
genius_album <- function(artist = NULL, album = NULL, info = "simple") {
# Obtain tracklist from genius_tracklist
album <- genius_tracklist(artist, album) %>%
# Iterate over the url to the song title
mutate(lyrics = map(track_url, genius_url, info)) %>%
# Unnest the tibble with lyrics
unnest(lyrics) %>%
# Deselect the track url
select(-track_url)
return(album)
}
```
### Notes:
As this is my first _"package"_ there will be many issues. Please submit an issue and I will do my best to attend to it.
There are already issues of which I am present (the lack of error handling). If you would like to take those on, please go ahead and make a pull request. Please contact me on [Twitter](twitter.com/josiahparry).