Zeeschuimer is a browser extension that monitors internet traffic while you are browsing a social media site, and collects data about the items you see in a platform's web interface for later systematic analysis. Its target audience is researchers who wish to systematically study content on social media platforms that resist conventional scraping or API-based data collection.
You can, for example, browse TikTok and later export a list of all posts you saw in the order you saw them in. Data can be exported as a JSON file or exported to a 4CAT instance for analysis and storage. Zeeschuimer is primarily intended as a companion to 4CAT, but you can also integrate its output into your own analysis pipeline.
Currently, it supports the following platforms:
- TikTok (posts and comments)
- Facebook (posts only)
- Instagram (posts only)
- Threads
- X/Twitter
- 9gag
- Imgur
- Douyin
- Gab
- Truth Social
- RedNote/Xiaohongshu
Platform support requires regular maintenance to keep up with changes to the platforms. If something does not work, we welcome issues and pull requests. See 'Limitations' below for some known limitations to data capture.
The extension does not interfere with your normal browsing and never uploads data automatically, only when you explicitly ask it to do so. It uses the WebRequest browser API to locally collect and parse the data search engines are sending to your browser as you use it.
This is Andy's fork of Zeeschuimer (andyfcx/zeeschuimer), which adds Chrome support and parsed CSV/JSON downloads on top of the upstream DMI extension. It has no signed releases of its own, so it is always installed from a local copy of the code, either way you get one:
- With git:
git clone https://github.com/andyfcx/zeeschuimer.git - Without git: open the repository page, click the green 'Code' button, then 'Download ZIP', and unzip it.
Then follow the steps for your browser below.
Because this fork is not signed, it is loaded as a temporary add-on, which stays installed until Firefox is closed and needs to be loaded again after that (repeating steps 2-3 below; your captured data is kept).
- Open Firefox and go to
about:debugging#/runtime/this-firefox. - Click 'Load Temporary Add-on...' and select the
manifest.jsonfile inside the folder you downloaded. - Go to
about:addons, open the 'Extensions' tab, and make sure Zeeschuimer is enabled there. - Its icon (
a yellow 'Z') should now appear in the toolbar; if you don't see it, click the puzzle-piece 'Extensions' icon to
find it there, and consider pinning it so it stays visible.
If you'd rather run the code straight from a git checkout instead of reloading a downloaded copy, you can also do so from the Firefox debugging console.
Chrome needs a manifest v3 version of the extension, which is built from the same source with a separate manifest
(manifest-chrome.json). From a terminal, in the folder you downloaded, run:
./build-chrome.sh
This assembles the extension in dist/chrome, as symlinks back to the source files. To install it, go to
chrome://extensions, switch on 'Developer mode', click 'Load unpacked' and select the dist/chrome folder. Chrome 111
or later is required. This also works in other Chromium-based browsers, such as Edge and Brave.
Because the assembled extension points at the source files, it only has to be loaded once: after editing the source,
pressing 'Reload' on the extension in chrome://extensions is enough. The script only needs to be run again when a file
is added or removed. For a self-contained copy and a zip file to distribute, run ./build-chrome.sh --package.
Capture works differently in Chrome. Chrome extensions cannot read response bodies from the browser's own networking API, and reading them in the page instead does not work either: a script injected into a page's own context is subject to that page's content security policy, which the supported platforms (Facebook in particular) do not allow extension scripts under. Chrome therefore captures through the same protocol the developer tools use, which has two consequences:
- Chrome asks for permission to 'debug' pages when the extension is installed, and shows a notification bar ('Zeeschuimer started debugging this browser') in tabs that capture is active in. The bar appears only for tabs showing a platform that capture is switched on for.
- The developer tools cannot be used in a tab while capture is active in it. If you open them anyway, capture stops for that tab; the interface says so, and closing the developer tools and reloading the page resumes it.
The interface shows how many tabs are being captured from and how much has been captured, so you can tell capture is working before exporting, and explains itself when it is capturing nothing. Everything else, including the exports, is identical to Firefox.
Note that removing the extension in chrome://extensions also clears its settings, so after loading it again capture is
switched off for every platform. Pressing 'Reload' on the extension keeps them.
However you installed it, the quickest way to check it worked: open Zeeschuimer's interface (its icon in the toolbar), switch capture on for Facebook, then browse to facebook.com and scroll a little. Zeeschuimer's item count for Facebook should go up as you scroll; click '.ndjson' or 'parsed .csv' next to it to export what was captured. See 'How to use' below for the rest.
A guide to using Zeeschuimer and 4CAT is available. Basic instructions are as follows:
Install the browser extension in a Firefox browser. A button with the Zeeschuimer logo (
) will appear in the browser toolbar. Click it
to open the Zeeschuimer interface. Enable capturing for the sites you want to capture from.
Note that after installation in Firefox, the extension icon may not be immediately visible in the toolbar. If you can't find Zeeschuimer's icon, look for the 'Extensions' icon (a puzzle piece); clicking it will show all available extensions that are not shown in the main browser toolbar.
Next, simply browse a supported platform's site. You will see the amount of items detected per platform increase as you browse. When you have the items you need, you can export the data as an ndjson file, or upload it to a 4CAT instance where a 4CAT dataset will be created from the uploaded items. You can then run 4CAT's analytical processors on the data.
To upload to 4CAT, copy the URL of the website of the 4CAT instance to the "4CAT instance" field at the top of Zeeschuimer's interface. You can then use the "to 4CAT" button to create a new 4CAT dataset from the captured data. After uploading, Zeeschuimer will show you a link and the ten most recently uploaded datasets are shown at the bottom of the interface.
Don't forget to reset the data as needed. For example, if you want to create a dataset for a given TikTok hashtag, first reset the TikTok data in Zeeschuimer, then go to the hashtag's "Explore" page on TikTok, and then upload the dataset when you've scrolled down enough to be satisfied with the amount of items.
If you find yourself scrolling a lot to collect data, consider using another browser extension to do it for you, for example FoxScroller.
The raw ndjson export contains everything the platform sent, which is a lot more than most analyses need. With the 'Offer parsed downloads' switch (on by default) each platform also gets 'parsed .csv' and 'parsed .json' buttons. These reduce every item to a flat row and remove duplicate posts:
| Platform | Fields |
|---|---|
post_id, post_url, creation_time, attachments, text, total_reaction_count, reactions, comment_count, share_count |
|
| TikTok | post_id, post_url, creation_time, attachments, text, author_name, author_id, like_count, comment_count, share_count, play_count |
| X/Twitter | post_id, post_url, creation_time, attachments, text, author_name, author_id, like_count, retweet_count, reply_count, quote_count, view_count, retweeted_from, promoted |
| Threads | post_id, post_url, creation_time, attachments, text, author_name, author_id, like_count, reply_count, repost_count, reposted_from |
The Facebook and TikTok parsers are ports of the ones in the zs-parser command line tool, so their output is interchangeable with it; the X/Twitter and Threads parsers only exist here. Other platforms fall back to the Facebook parser, as the command line tool does; for those, the raw ndjson export is usually the better choice.
A retweet's or repost's own text is empty or cut off, so the text, media and engagement counts of the post that was
retweeted or reposted are used, while author_name and author_id stay whoever retweeted or reposted it and
retweeted_from/reposted_from name the original author. Tweets longer than 280 characters keep their full text, and
for a video the highest quality variant is listed as the attachment. The .csv file is written with a byte order mark so that spreadsheet software recognises it as
UTF-8, and lists (attachments, reactions) are joined with '; ' in a single column. Switching the option off hides the
buttons again; the setting is remembered.
Due to the technical limitations, it may not be possible to collect all items from all 'views' for each supported platform. The following limitations are known:
- Instagram items that cannot be captured:
- Stories
- Posts from the 'Tagged' and 'Reels' tabs on a profile page
- Posts from the 'Saved' overview of bookmarked posts
- Posts from the 'For You' feed on the 'Explore' page (the 'Not personalized' feed does work)
- 'Suggested for you' and 'Sponsored' posts on the front page feed
- TikTok items that cannot be captured:
- Live streams
- In Chrome, capture only runs in tabs the extension is attached to, which it does when a tab navigates to a platform that capture is switched on for. Responses a tab loaded before that (for example when you switch a platform on while its page is already open) are not captured; reloading the page captures them.
For some platforms, the level of detail of the data that can be collected depends on the page it is captured from:
- Pinterest items may lack some metadata unless captured from the individual post's page, most notably the timestamp of the post.
- RedNote/Xiaohongshu items will often lack the item's post description, timestamp, and video URL, unless captured by opening the post's own page/clicking it in an overview.
Note that these are known limitations; data capture may break or change based on platform changes. Always cross-reference captured data with what you are seeing in your browser.
Zeeschuimer was developed by Stijn Peeters for the Digital Methods Initiative and is licensed under the Mozilla Public License, 2.0. Refer to the LICENSE file for more information.
Graphics based on an image generated by Dall-E, for the prompt 'detail of a 1914 metaphysical painting by giorgio de chirico depicting a buccaneer pensively looking out over the open sea'. Interface icons by Font Awesome. Open Sans and Lobster fonts from Google Fonts.
Development is supported by the Dutch PDI-SSH foundation through the CAT4SMR project.