Skip to main content

A library for creating media bots.

Project description


OpenMediaBot is a Python library for creating media bots.

What exactly is a media bot?

The name pretty much says it all. A media bot is a bot dedicated to supplying various media. This can include but is not limited to photo, audio, or video.

Table of Contents


You will need Python 3.7 or greater installed on your system in order to run OpenMediaBot.

The recommended way to install OpenMediaBot is by using pip. Just run the following command:

pip install OpenMediaBot --user

Database Structure

OpenMediaBot keeps track of all media in a SQLite3 Database. The schema is as follows:


The ID is a unique identifier for the file. For local files, it is the file path. For Google Drive, it is the Google Drive file ID. Location denotes where the file is, for example, LOCAL or DRIVE would be valid values here.

Media Objects

Media within OpenMediaBot is handled using a special object.

from OpenMediaBot import Media

media = Media(data, mimetype, name, id)

The "data" argument takes a file-like object. The "id" parameter is a unique identifier for the file. For a local file, this is the file path. For a Google Drive file, this is the Google Drive file ID.


All bots inherit from the Bot baseclass. This class handles things such as database management, downloading photos from external sources, and setting configuration. It has several methods.

Method Description Arguments
updatedb() Update the database, or create it if it does not exist. None
resetdb() Sets the "posted" value of every database entry to False. None
DownloadFromDrive() Returns a media object constructed from a Google Drive File ID. id
GetRandom() Returns a media object created from a random database entry. no_repeat=True

In theory, OpenMediaBot can be designed to work with any platform. Currently, it is only designed to work with Twitter out of the box.

Twitter Bots

Twitter bots are handled using the TwitterBot class, which is a subclass of Bot. The class can be instantiated as follows:

from OpenMediaBot import TwitterBot

bot = TwitterBot()

In order to post to Twitter, you must be authenticated using Oauth 1. OpenMediaBot requires these to be passed in a JSON file formatted as follows:

{"CONSUMER_KEY":<your API key>,
"CONSUMER_SECRET":<your API key secret>,
"ACCESS_TOKEN":<your Oauth token>,
"ACCESS_TOKEN_SECRET":<your Oauth token secret>}

These credentials can be obtained by registering for a Twitter Developer Account and then creating a standalone app or project.

By default, OpenMediaBot looks for the credential file in creds/twitter_creds.json. If you would like to provide the file in a different location, pass it to the constructor as twitter_credfile = "/path/to/credfile".

As of now, TwitterBot has one special method.

Method Description Arguments
post() Posts a piece of media to Twitter. media="random", status=None, updatedb=True

The agruments of post() deserve a little bit of extra explaination. media must be an OMB media object. The default behavior is just to pick a random one from the database. updatedb refers to if the database is updated on each run. status is the text to be posted along with the media.

Configuration Options

There are many options that can be passed to configure the bot. These can either be passed as keyword arguments, or passed in a JSON file using the configfile= in the bot constructor.

Option Description Type Default
name Name of the bot. This will also be used as the name for the table in the database. string OpenMediaBot
db Path to the database file. Also accepts :memory: for an in-memory database. string media.db
logpath Path to log file. string None
drive_folders Drive Folder IDs. array of strings None
local_folders Paths to local folders. array of strings None
gdrive_settings Path to the settings.yaml file used for Google Drive authentication. string settings.yaml
dm_errors* Send reports via Twitter DMs when the bot fails to post. bool True
admin_ids* The Twitter IDs of the users to DM with error reports. array of integers None

*These options are only available for a Twitter bot

Google Drive

OpenMediaBot uses PyDrive2 to interface with Google Drive. Instructions on how to obtain Google Oauth2 credentials can be found here. OpenMediaBot utilizes a settings.yaml file in order automate Google Drive Authentication. Create a settings.yaml which contains the following:

client_config_backend: settings
client_config_file: <Path/to/oauth/creds/file/>
  client_id: <your oauth client id>
  client_secret: <your oauth client secret>

save_credentials: True
save_credentials_backend: file
save_credentials_file: <path/to/jsonfile/in/which/to/save/creds>

get_refresh_token: True


More info on settings.yaml files can be found here. By default, OpenMediaBot looks for a settings.yaml in the directory the script is being run from. If it is not located there or has a different name, be sure to pass its location to the bot constructor or configuration file.


The following is an example of an OpenMediaBot Twitter bot.

Keyword Arguments Method

from OpenMediaBot import TwitterBot

bot = TwitterBot(admin_ids=[<Admin Twitter ID>],
drive_folders=[<Drive Folder ID>],

Configuration File Method

from OpenMediaBot import TwitterBot

bot = TwitterBot(configfile="config.json")

The contents of config.json:

{"admin_ids":[<Admin Twitter ID>], 
"drive_folders":[<Drive Folder ID>],

This is a pretty simple implementation of OpenMediaBot.

If you find a bug, or have a feature request, please open a GitHub issue. Have any questions about OpenMediaBot? Feel free to reach out on GitHub discussions!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

OpenMediaBot-1.1.3.tar.gz (13.4 kB view hashes)

Uploaded source

Built Distribution

OpenMediaBot-1.1.3-py3-none-any.whl (14.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page