imessagedb 1.4.7

Reads and displays the Apple iMessage database

imessagedb

Reads and displays the Apple iMessage database

Installation

$ pip install imessagedb

Usage

imessagedb can be used as a library for accessing and parsing the iMessasge chat database stored at ~/Library/Messages/chat.db, or it can be used on the command line to display the contents.

How it works

The command line version wraps the functions provided and outputs data based on the configuration available in the configuration file, as well as command line arguments.

The way that iMessage identifies conversation particpants is by a handle, which can be their phone number or email address. To make it easier, you can map handles in the configuration file.

You can also specify the type of output (text or html) and the time frame of the messages. At this point imesssagedb will pull all messages from that person, regardless of the chat that it is part of.

If you specify html output, imessagedb will copy your attachments so that they are accessible to the web browser. In addition, it will convert certain types of attachments so that they can be viewed in the browser. For instance, it will convert HEIC files to PNG so that they browser can display it, and will convert various type of movie files to mp4 and various audio files to mp3. If you have many attachments, this can take a long time and take a lot of space.

Example Output

This is what the default html version looks like. Note that I am hovering over one of the links to show the image.

This is the same conversation rendered in text.

Command Line

imessagedb [-h] [--handle [HANDLE ...] | --name NAME] [-c CONFIGFILE]
               [-o OUTPUT_DIRECTORY] [--database DATABASE] [-m ME]
               [-t {text,html}] [-i] [-f | --no_copy] [--no_attachments] [-v]
               [--start_time START_TIME] [--end_time END_TIME]
optional arguments:
  -h, --help            show this help message and exit
  --handle [HANDLE ...]
                        A list of handles to search against
  --name NAME           Person to get conversations about
  -c CONFIGFILE, --configfile CONFIGFILE
                        Location of the configuration file
  -o OUTPUT_DIRECTORY, --output_directory OUTPUT_DIRECTORY
                        The output directory where the output and attachments
                        go
  --database DATABASE   The database file to open
  -m ME, --me ME        The name to use to refer to you
  -t {text,html}, --output_type {text,html}
                        The type of output
  -i, --inline          Show the attachments inline
  -f, --force           Force a copy of the attachments
  --no_copy             Don't copy the attachments
  --no_attachments      Don't process attachments at all
  -v, --verbose         Turn on additional output
  --start_time START_TIME
                        The start time of the messages
  --end_time END_TIME   The end time of the messages
  --split_output SPLIT_OUTPUT
                        Split the html output into files with this many messages per file
  --version             Show the version number and exit
  --get_handles         Display the list of handles in the database and exit
  --get_chats           Display the list of chats in the database and exit

Command line options

-h prints a help message |

--handle [HANDLE ...] A list of handles to search against. For instance, '--handle [phone] [e-mail]'.

--name NAME A person to search for. The mapping of person to handle is in the configuration file (see below)

*** Note that you can only have one of --handle or --name, not both ***

-c CONFIGFILE, --configfile CONFIGFILE The location of the configuration file. If the file does not exist, a default configuration file will be created there. If this option is not provided, the default location is ~/.conf/iMessageDB.ini.

-o OUTPUT_DIRECTORY, --output_directory OUTPUT_DIRECTORY The output directory where the output and attachments go. If this option is not provided, the default location is your home directory. The files will be ~/NAME.html and attachments will be in ~/NAME_Attachments.

--database DATABASE The database file to open. If this option is not provided it will default to ~/Library/Messages/chat.db, which is where Apple puts it.

-m ME, --me ME The name to use to refer to you in the output. If this option is not provided it will default to Me.

-t {text,html}, --output_type {text,html} The type of output, either text or html. If this option is not provided it will default to html.

--start_time START_TIME
--end_time END_TIME By default, the program will process all messages. If you want to restrict that to particular timeframe, you can specify the --start-time and/or --end_time options

--split_output SPLIT_OUTPUT Split the html output into files with this many messages per file

-i, --inline Show the attachments inline. By default, the attachments will show as links that you can hover over and it will pop up the attachment. With this option, it will put them inline, which will make your output much busier and take a lot more memory in your browser.

-f, --force Force a copy of the attachments. By default, if the attachment already exists in the destination directory, it will not re-copy the file, but this will force it to re-copy it.

--no_copy Don't copy the attachments. This will make them inaccessible for viewing

--no_attachments Do not show the attachments at all

-v, --verbose Turn on additional output

--version Shows the version number and exits

--get_handles Display the list of handles in the database and exit

--get_chats Display the list of chats in the database and exit

Configuration File

The configuration file is in configparser format. Here is the template that is created by default:

[CONTROL]

# Whether or not to copy the attachments into a different directory. This is needed for two reasons:
#  1) The web browser does not have access to the directory that the attachments are stored, so it cannot display them
#  2) Some of the attachments need to be converted in order to be viewed in the browser

copy = True

# The directory to put the output. The html file will go in {copy_directory}/{Person}.html,
#   and the attachments will go in {copy_directory}/{Person}_Attachments. If you specify HOME, then
#   it will put it in your home directory

copy directory = HOME

# If the file already exists in the destination directory it is not recopied, but that can be overridden by
#  specifying 'force copy' as true

force copy = False

# 'Skip attachments' ignores attachments

skip attachments = False

# Additional details show some other information on each message, including the chat id and any edits that have 
#  been done

additional details = False

# Some extra verbosity if true

verbose = True

[DISPLAY]

# Output type, either html or text

output_type = html

# Number of messages in each html file. If this is 0 or not specified, it will be one large file.

output split = 1000

# Inline attachments mean that the images are in the HTML instead of loaded when hovered over

inline attachments = False

# Popup location is where the attachment popup window shows up, and is either 'upper right', 'upper left' or 'floating'

popup location = upper right

# 'me' is the name to put for your text messages
me = Me

# The color for the name in text output. No color is used if 'use text color' is false.
#  The color can only be one of the following options:
#   black, red, green, yellow, blue, magenta, cyan, white, light_grey, dark_grey,
#   light_red, light_green, light_yellow, light_blue, light_magenta, light_cyan

use text color = True
me text color = blue
them text color = magenta
reply text color = light_grey

# The background color of the text messages for you and for the other person in html output
# The options for colors can be found here: https://www.w3schools.com/cssref/css_colors.php

me html background color = AliceBlue
them html background color = Lavender

# The background color of the thread in replies

thread background = HoneyDew
me thread background = AliceBlue
them thread background = Lavender

# The color of the name in the html output

me html name color = Blue
them html name color = Purple


[CONTACTS]

# A person that you text with can have multiple numbers, and you may not always want to specify the full specific
#  number as stored in the handle database, so you can do the mapping here, providing the name of a person,
#  and a comma separated list of numbers

Samantha: [phone], [e-mail], 
   [e-mail]
Abe: [phone]
Marissa: [phone]

Library Usage

import imessagedb
database = imessagedb.DB()

• TODO - More usage here

Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

imessagedb was created by Xev Gittler. It is licensed under the terms of the MIT license.

Documentation

Full documentation available at https://imessagedb.readthedocs.io/en/latest/