Welcome to slacksound’s documentation!¶

Contents:

SlackSound¶

Create playlists democratically by reactions in Slack

!! THIS IS STILL A BETA !!

Documentation: https://slacksound.readthedocs.org/en/latest

Features¶

Get Youtube videos reactions from message attachments and add the song to a Spotify playlist.

How does it work¶

The application acts as a middle man between Slack and Spotify by getting the reactions count from a message’s attachment and then looking up the title on Spotify’s. If the title has been found, it will add the one that has best popularity to the queue.

In order to the bot pick up the song, a user must paste a Youtube URL in the channel. The bot will start looking for reactions on that URL and get the title of the video which it will be used as a search text for Spotify.

A message will be shown back to the channel whether the bot could add the song to the playlist or not.

It is worth mention that the tracks of the playlist will be removed at every time the bot it is started. This is by design as it in a jukebox.

Installation¶

At the command line:

$ pip install slacksound

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv slacksound
$ pip install slacksound

Usage¶

Slack¶

The first step is to create a Slack bot. Instructions can be found here under the title How do I create custom bot users for my workspace?

You can give it a name and assign an avatar to it. This will make it easier later when reading messages from it on your channel.

Once your bot is created, it will generate a token for you in order to communicate to Slack API.

Do not forget to add the bot user to your channel!

Spotify¶

The second step is to register an APP in your Spotify account. You can follow the instructions on how to do this in here

Configuration¶

Once you have all the details, you are going to need to create a configuration file so that the CLI can get all the parameters.

By default, the program will look into a hidden file named .slacksound under your home directory but you can also specify the location manually.

slacksound --configuration /Users/slack/myconfig.cfg

The configuration must be like as per below:

[spotify]
username = <username>
password = <password>
client_id = <client_id>
client_secret = <client_secret>
playlist = <playlist_name>
callback_url = <callback_url>
scope = <scope>

[slack]
token = <bot_token>
channel = <channel_name>
reaction = <emoji_reaction>
count = <number_of_reaction_counts>

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Submit Feedback¶

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.

Get Started!¶

Ready to contribute? Here’s how to set up slacksound for local development.

Clone your fork locally:

$ git clone https://github.com/wefner/slacksound

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your clone for local development:
```
$ mkvirtualenv slacksound
$ cd slacksound/
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.

Commit your changes and push your branch to the server:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a merge request

slacksound¶

slacksound package¶

Submodules¶

slacksound.slackapi module¶

Main code for slackapi

class slacksound.slackapi.Attachment(attachment_details)[source]¶

Bases: object

Model for an Attachment

Not all attributes are populated here though.

https://api.slack.com/docs/message-attachments

author_link¶

A valid URL that will hyperlink the author_name text mentioned above.

Returns: string

author_name¶

Small text used to display the author’s name.

Returns: string

title¶

Title of the attachment

Returns: string

class slacksound.slackapi.Channel(slack_instance, channel_details)[source]¶

Bases: object

Model for a Channel

Not all attributes are populated here though.

https://api.slack.com/types/channel

channel_id¶

Channel ID

Returns: string

created¶

Unix time converted to datetime object

Returns: datetime object

history¶

Chat history of the channel

Returns: list of Message objects

is_general¶

Whether the channel is general or not

Returns: boolean

name¶

Name of the channel

Returns: string

name_normalized¶

Normalized name of the channel

Returns: string

class slacksound.slackapi.Group(slack_instance, group_details)[source]¶

Bases: object

Model for a group

Not all attributes are populated here though.

https://api.slack.com/types/group

created¶

Unix time converted to datetime object

Returns: datetime object

group_id¶

Group ID

Returns: string

history¶

Chat history of the group

Returns: list of Message objects

is_general¶

Whether the group is general or not

Returns: boolean

name¶

Name of the group

Returns: string

name_normalized¶

Normalized name of the group

Returns: string

class slacksound.slackapi.Member(member_details)[source]¶

Bases: object

Model for a Member

Not all attributes are populated here though.

https://api.slack.com/types/user

color¶

Used in some clients to display a colored username.

Returns: string

deleted¶

Active/Inactive users

Returns: boolean

email¶

Email of the member

Returns: string

is_admin¶

Whether this user is admin or not

Returns: boolean

member_id¶

Member ID

Returns: string

class slacksound.slackapi.Message(message_details)[source]¶

Bases: object

Model for a Message

Not all attributes are populated here though.

https://api.slack.com/events/message

attachments¶

Attachments for a Message, if any

Returns: list of Attachment objects

datetime¶

Unix time converted to datetime object

Returns: datetime object

reaction¶

Reactions of the message

Returns: list of Reaction objects

text¶

Text of the message

Returns: string

type¶

SubType of the Message

Returns: string

unix_time¶

Unix time. Useful for time comparison

Returns: float

user¶

ID of the user speaking or sent the message

Returns: string

class slacksound.slackapi.Reaction(reaction_details)[source]¶

Bases: object

Model for a Reaction

These are Emoji icons for a message

count¶

Count of a reaction

Returns: integer

name¶

Name of the reaction

Returns: string

users¶

User IDs who reacted on the reaction

Returns: list of user ID

class slacksound.slackapi.Slack(token, bot=False)[source]¶

Bases: object

SlackClient Wrapper

channels¶

Gets all channels in a Slack team.

Parameters:	**kwargs – extra kwargs

Returns: list of Channel objects

get_channel_by_name(channel_name)[source]¶

Gets one channel in a Team

Parameters:	channel_name – string

Returns: Channel object

get_group_by_name(group_name)[source]¶

Gets one group in a Team

Parameters:	group_name – string

Returns: Group object

groups¶

Gets all groups in a Slack team.

Parameters:	**kwargs – extra kwargs

Returns: list of Group objects

post_message(message, channel)[source]¶

Posts a message in a group or channel as the user who is owner of the token

Parameters:	message – string channel – string

Returns:

users¶

Gets all users in a Slack team.

Parameters:	**kwargs – extra kwargs

Returns: list of Member objects

slacksound.slacksound module¶

Main code for slacksound

slacksound.slacksound.SlackSound¶: alias of Config

slacksound.slacksound.connect_spotify(credentials)[source]¶

slacksound.slacksound.get_arguments()[source]¶: This get us the cli arguments. Returns the args as parsed from the argsparser.

slacksound.slacksound.get_config_details(credentials)[source]¶

slacksound.slacksound.get_credentials(filename=False)[source]¶

Parameters:	filename – path of the filename

Reads credentials file

Locates credentials file in ~/.slacksound and loads them by default.

This file must be a INI type and if a filename is provided, it will try to load this one.

Returns:	ConfigParser instance

slacksound.slacksound.get_most_popular_track(tracks)[source]¶

slacksound.slacksound.main()[source]¶: Main method. This method holds what you want to execute when the script is run on command line.

slacksound.slacksound.sanitize_title(title)[source]¶

Gets the artist and song name only

Splits the string by the the first open parenthesis and gets first item in the list

Examples

in: ‘Eric Clapton - Cocaine (Original Video)’ out: ‘Eric Clapton - Cocaine’

Parameters:	title – string

Returns: string

slacksound.slacksound.setup_logging(args)[source]¶: This sets up the logging. Needs the args to get the log level supplied :param args: The arguments returned gathered from argparse

slacksound.slacksoundexceptions module¶

Custom exception code for slacksound

slacksound.spotifyclient module¶

Main code for spotifyclient

class slacksound.spotifyclient.Playlist(username, spotify_instance, playlist_details)[source]¶

Bases: object

Playlist model

add_track(track_id)[source]¶

Add a track to the playlist

Parameters:	track_id – string

Returns: Boolean

collaborative¶

Whether it is collaborative or not

Returns: boolean

delete_all_tracks()[source]¶

Deletes all tracks that are in the playlist

Returns: Snapshot ID

href¶

Link of the Playlist

Returns: string

name¶: Name of the Playlist Returns:

playlist_id¶

Playlist ID

Returns: string

public¶

Whether it is a public playlist or not

Returns: boolean

tracks¶

Get all tracks in the playlist

Returns: list of Track objects

uri¶

URI of the playlist

Returns: string

class slacksound.spotifyclient.SpotifyClient(client_id, client_secret, username, password, callback, scope)[source]¶

Bases: object

get_playlist_by_name(playlist_name)[source]¶

Looks into all playlists and returns the one that matched

Parameters:	playlist_name – string

Returns: Playlist object

get_track_by_title(track_title, limit=5)[source]¶

Looks up on Spotify for a text string and returns tracks if found

The limit is an optional argument to retrieve more results

Examples

‘Eric Clapton - Cocaine’ “Bon Jovi - Livin’ On A Prayer”

Parameters:	track_title – string limit – integer

Returns: list of Track objects

playlists¶

Get all playlists for the user within its scope

It also passes username and Spotify instance as it is needed for Playlist object

Returns: list of Playlist objects

class slacksound.spotifyclient.Track(track_details)[source]¶

Bases: object

Model for a Track

duration_ms¶

Duration in milliseconds

Returns: integer

name¶

Name of the track

Returns: string

popularity¶

Popularity of the track

Returns: integer

track_id¶

Track ID

Returns: string

uri¶

URI of the track

Returns: URI

Module contents¶

slacksound package

Import all parts from slacksound here

Credits¶

Development Lead¶

Oriol Fabregas <fabregas.oriol@gmail.com>

Contributors¶

None yet. Why not be the first?

History¶

0.0.1 (2017-10-13)¶

First release
Methods for Spotify API
Slackclient wrapper

0.0.2 (2017-10-14)¶

CLI draft
Credentials parsing
Minimal logic

0.0.3 (2017-10-14)¶

Reaction name and reaction count configurable

0.0.4 (2017-10-26)¶

Refactored SpotifyClient with objects and methods
Refactored SlackSound interface

0.0.5 (2017-10-27)¶

Entrypoint for main

0.1.0 (2017-10-27)¶

Try a private channel first or fallback as a public one if fails

0.1.1 (2017-10-27)¶

Logging for user

0.1.2 (2017-10-27)¶

Fix local variable referenced before assignment

Welcome to slacksound’s documentation!¶

SlackSound¶

Features¶

How does it work¶

Installation¶

Usage¶

Slack¶

Spotify¶

Configuration¶

Contributing¶

Submit Feedback¶

Get Started!¶

slacksound¶

slacksound package¶

Submodules¶

slacksound.slackapi module¶

slacksound.slacksound module¶

slacksound.slacksoundexceptions module¶

slacksound.spotifyclient module¶

Module contents¶

Credits¶

Development Lead¶

Contributors¶

History¶

0.0.1 (2017-10-13)¶

0.0.2 (2017-10-14)¶

0.0.3 (2017-10-14)¶

0.0.4 (2017-10-26)¶

0.0.5 (2017-10-27)¶

0.1.0 (2017-10-27)¶

0.1.1 (2017-10-27)¶

0.1.2 (2017-10-27)¶

Indices and tables¶