# Animated GIF Player for Matrix Portal ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/096/292/medium800/led_matrices_banner.jpg?1603509670) There’s something **eye-catching** about LED matrix graphics that you don’t get with a normal LCD display. Maybe it’s the brightness or the ultra-saturated colors. Perhaps that’s why they’re increasingly popular in advertising signage. This guide uses an **Adafruit MatrixPortal M4** _or_ **Adafruit MatrixPortal S3** and  **RGB LED matrix** to create an **animated GIF player** that’s drag-and-drop easy, like a pixelated version of a digital photo frame. Use it to make a holiday window display or to advertise your favorite shawarma cart. This is a **different approach** than used in our [Sprite Sheet Animation](https://learn.adafruit.com/pixel-art-matrix-display/sprite-sheet-animation) and [Tombstone](https://learn.adafruit.com/tombstone-matrix-portal/code-the-sprite-sheet-animation-display) guides. There, the animation is controlled by **CircuitPython** code…letting you control speed or interactivity or anything else you can dream up. But when you’d like something simpler, **animated GIFs are easy and ubiquitous** …you can likely find some ready-made with a few internet searches. Toss a bunch on the Matrix Portal flash drive and it plays them back in a loop. ![](https://cdn-learn.adafruit.com/assets/assets/000/096/296/medium800/led_matrices_ruby.jpg?1603510888) # Animated GIF Player for Matrix Portal ## Quickstart ![](https://cdn-learn.adafruit.com/assets/assets/000/096/293/medium800/led_matrices_goo.jpg?1603510835) The GIF player loads images from the Matrix Portal’s **flash filesystem**. Although it’s an Arduino-based project, it’s necessary to **temporarily install CircuitPython** on the board to set up that drive for the first time. _If you’ve previously installed CircuitPython, then these steps are already done…_ ## Matrix Portal M4 Setup 1. [**Visit the CircuitPython download page for Matrix Portal M4**](https://circuitpython.org/board/matrixportal_m4/) and download a current **.UF2** file. 2. Connect the MatrixPortal board to your computer via **USB** cable. 3. **Double-click** the board’s **reset** button. 4. After a few seconds, the onboard NeoPixel should turn **green** and a drive called **MATRIXBOOT** will appear on your computer. 5. Drag the CircuitPython .UF2 file to this drive and wait several seconds for it to install. The MATRIXBOOT drive will be replaced by a new drive called **CIRCUITPY**. ## MatrixPortal S3 Setup 1. [Visit the CircuitPython download page for MatrixPortal S3](https://circuitpython.org/board/adafruit_matrixportal_s3/) and download a current **.UF2** file. 2. Connect the MatrixPortal board to your computer via **USB** cable. 3. **Double-click** the board’s **reset** button. 4. After a few seconds, the onboard NeoPixel should turn **green** and a drive called **MATRIXS3BOOT** will appear on your computer. 5. Drag the CircuitPython .UF2 file to this drive and wait several seconds for it to install. The **MATRIXS3BOOT** drive will be replaced by a new drive called **CIRCUITPY**. **Create a folder** called **gifs** on this drive. That’s where we’ll put images for playback. ### **NOTE:** you _must_ create the **gifs** folder on the CIRCUITPY drive and put images in there, or _nothing will happen._ Then download the precompiled **.UF2** file for your board: ### Matrix Portal M4 [MATRIXPORTAL-M4-ANIMATED-GIF.UF2](https://cdn-learn.adafruit.com/assets/assets/000/096/692/original/MATRIX_PORTAL_ANIMATED_GIF.UF2?1604342291) ### MatrixPortal S3 [MatrixPortalS3-Animated-GIF.UF2](https://cdn-learn.adafruit.com/assets/assets/000/132/878/original/MatrixPortalS3-Animated-GIF.UF2?1727967346) ### **NOTE:** this ready-made version works with a **64x32** pixel matrix. The code _can_ handle other sizes but you’ll need to adjust and compile the code yourself in that case, explained on the “Compiling and Customizing” page. Installing this is similar to CircuitPython above: 1. Connect the MatrixPortal board to your computer via **USB** cable. 2. **Double-click** the board’s **reset** button. 3. After a few seconds, the onboard NeoPixel should turn **green** and a drive called **MATRIXBOOT** or **MATRIXS3BOOT** will appear on your computer. 4. Drag the GIF player .UF2 file to this drive and wait several seconds for it to install. The GIF player will start running on your board and the  **BOOT**  drive will be replaced by a new drive called  **CIRCUITPY**. Now you just need to load up the **gifs** folder with suitable images, and **tap the reset button to restart**. Danger: # Animated GIF Player for Matrix Portal ## Prepare GIFs ![](https://cdn-learn.adafruit.com/assets/assets/000/096/294/medium800/led_matrices_rings.jpg?1603510852) The GIF player **does not scale** images. If they’re a _little bit_ smaller or larger than the LED matrix, they’ll be centered or cropped to fit. Some GIFs do fine with a little cropping…but if they’re _much_ larger than the matrix, as most GIFs you’ll find on the internet are, they’ll still play but won’t make any sense with such a small area clipped out. You may have to do some **prep work…** These techniques have already been covered in other guides. Rather than repeat ourselves, we’ll **link** to those guides and provide some **commentary** with how things may be different when using an LED matrix. [A similar project for the original PyPortal (like a MatrixPortal with an LCD display) explains the use of an online tool — EZGIF — for **resizing and optimizing GIF images** , so you don’t need to own any special image editing software](https://learn.adafruit.com/pyportal-animated-gif-display/convert-your-gif) (opens in new window). Use **64** and **32** for the width and height settings (rather than 320 and 240) if that’s what matches your matrix. Keep the other settings as recommended in that guide. With the smaller pixel dimensions of the LED matrix, the Optimize and Reduce Frames steps can be **ignored**. It’s no trouble decoding these small GIFs at full speed! GIFs played on the LED matrix may appear overly bright and washed-out. **[A different guide explains how to adjust for this](https://learn.adafruit.com/image-correction-for-rgb-led-matrices/animated-gifs-using-imagemagick)** (opens in new window). Rather than an online tool, this guide uses software installed on your computer to make the adjustment. This approach _does_ require some **command-line** chops…but…since this can handle the same scaling and cropping options as the EZGIF method above, you don’t need to run your image through multiple tools, it’s a quicker one-stop solution. ![](https://cdn-learn.adafruit.com/assets/assets/000/096/297/medium800/led_matrices_firework.jpg?1603511066) **IMPORTANT NOTE: the AnimatedGIF library _does not handle_ interlaced GIFs (this is a tradeoff for handling arbitrarily long/complex animations). When saving or converting GIF images, be certain that interlacing is OFF.** If using [ImageMagick](https://learn.adafruit.com/image-correction-for-rgb-led-matrices/animated-gifs-using-imagemagick) for conversion, this can be done with the -interlace None option, as shown in the matrix guide linked above. # Animated GIF Player for Matrix Portal ## Compiling and Customizing ![](https://cdn-learn.adafruit.com/assets/assets/000/096/295/medium800/led_matrices_sine.jpg?1603510864) If the GIF player doesn’t quite do what you want (different matrix size, etc.), the source code can be tweaked and recompiled. **This assumes you already have the Arduino development environment installed for the Matrix Portal M4 or MatrixPortal S3.** If you’ve not done this before, [these steps are described in the MatrixPortal M4 introductory guide](https://learn.adafruit.com/adafruit-matrixportal-m4/arduino-ide-setup) or [the MatrixPortal S3 guide](https://learn.adafruit.com/adafruit-matrixportal-s3/arduino-ide-setup). Additionally, this requires that the **Adafruit\_Protomatter** and **AnimatedGIF** Arduino libraries be installed. This process is also explained in the guide linked above, [or in the Adafruit\_Protomatter guide](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library/installing-arduino-library) (opens in new window). Once installed in the Arduino IDE, you can find the animated GIF player among the Protomatter library examples… **File→Examples→Adafruit Protomatter→animated\_gif** [You can also find the project source code on Github](https://github.com/adafruit/Adafruit_Protomatter/blob/master/examples/animated_gif/animated_gif.ino), but will still need the Protomatter library installed. ### **Changing the GIF folder and playback time** Near the top of the code, starting around line 26, you’ll see these two lines: ```cpp char GIFpath[] = "/gifs"; // Absolute path to GIFs on CIRCUITPY drive uint16_t GIFminimumTime = 10; // Min. repeat time (seconds) until next GIF ``` The first of these is the folder name containing the GIF images to play. By default this is `gifs`, but you can change that here if you like. Second line tells how long to repeat each GIF. This is a _minimum_ time, in seconds. With the default value of `10` here, a short 1-second GIF would be repeated 10 times before advancing to the next image…while a long 10+ second GIF will play only once. GIF playback is not _truncated_ to this time, they will always play back in their entirety _at least_ once. ### **Using different matrix sizes** The next couple of lines define the matrix dimensions… ```cpp #define WIDTH 64 // Matrix width in pixels #define HEIGHT 32 // Matrix height in pixels // Maximim matrix height is 32px on most boards, 64 on MatrixPortal if the // 'E' jumper is set. ``` **NOTE:** 64x64 matrices require **soldering** between two pads on the MatrixPortal board. This is [explained in the MatrixPortal guide](https://learn.adafruit.com/adafruit-matrixportal-m4/pinouts#step-3072814) (see “Address E Line Jumper” at the bottom). Other matrix sizes (64x32 and 32x16) are plug-and-play with just the code change. Make sure you have the correct board type selected: **Tools→Board→Adafruit Matrix Portal M4** **or!** **Tools→Board→Adafruit MatrixPortal ESP32-S3** Compile and upload to the board, and it should work at the new size or new folder & time settings. **HELPFUL TIP: remember how you double-tap reset to install a .UF2 file onto the MatrixPortal board? _This works both ways!_ Once you’ve got the code configured and running how you like, double-tap the reset button and copy the file CURRENT.UF2 _off_ the board to your computer. Now it’s easy to reinstall your custom version any time. This file can be renamed something descriptive if you like, just keep the .UF2 at the end.** # Animated GIF Player for Matrix Portal ## Example GIFs These images will look a bit dark in your browser but will play correctly on the LED matrix. Right-click and “Save Image…” to download each GIF. Remember to put these _inside the **gifs** folder_ on the CIRCUITPY drive. ![](https://cdn-learn.adafruit.com/assets/assets/000/096/281/medium800/led_matrices_blobbo.gif?1603496783) ![](https://cdn-learn.adafruit.com/assets/assets/000/096/282/medium800/led_matrices_firework.gif?1603496791) ![](https://cdn-learn.adafruit.com/assets/assets/000/096/283/medium800/led_matrices_hop.gif?1603496798) ![](https://cdn-learn.adafruit.com/assets/assets/000/096/284/medium800/led_matrices_ruby_walk.gif?1603496806) ![](https://cdn-learn.adafruit.com/assets/assets/000/096/285/medium800/led_matrices_sine_tube.gif?1603496814) ![](https://cdn-learn.adafruit.com/assets/assets/000/096/286/medium800/led_matrices_three_rings.gif?1603496822) ## Featured Products ### Adafruit Matrix Portal S3 CircuitPython Powered Internet Display [Adafruit Matrix Portal S3 CircuitPython Powered Internet Display](https://www.adafruit.com/product/5778) Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it... Out of Stock [Buy Now](https://www.adafruit.com/product/5778) [Related Guides to the Product](https://learn.adafruit.com/products/5778/guides) ### Adafruit Matrix Portal - CircuitPython Powered Internet Display [Adafruit Matrix Portal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4745) Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories, for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it... In Stock [Buy Now](https://www.adafruit.com/product/4745) [Related Guides to the Product](https://learn.adafruit.com/products/4745/guides) ### Adafruit Matrix Portal Starter Kit - ADABOX 016 Essentials [Adafruit Matrix Portal Starter Kit - ADABOX 016 Essentials](https://www.adafruit.com/product/4812) If you missed out on [AdaBox016](https://www.youtube.com/watch?v=Yr3F8EBAVBU), it's not too late for you to pick up the parts necessary to build many of the projects! It doesn't come with tissue paper or the nifty extras, but it does have all the electronic goodies you... In Stock [Buy Now](https://www.adafruit.com/product/4812) [Related Guides to the Product](https://learn.adafruit.com/products/4812/guides) ### 64x32 RGB LED Matrix - 6mm pitch [64x32 RGB LED Matrix - 6mm pitch](https://www.adafruit.com/product/2276) Bring a little bit of Times Square into your home with this sweet 64x32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked really... In Stock [Buy Now](https://www.adafruit.com/product/2276) [Related Guides to the Product](https://learn.adafruit.com/products/2276/guides) ### 64x32 RGB LED Matrix - 5mm pitch [64x32 RGB LED Matrix - 5mm pitch](https://www.adafruit.com/product/2277) Bring a little bit of Times Square into your home with this sweet 64x32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked really... In Stock [Buy Now](https://www.adafruit.com/product/2277) [Related Guides to the Product](https://learn.adafruit.com/products/2277/guides) ### 64x32 RGB LED Matrix - 3mm pitch [64x32 RGB LED Matrix - 3mm pitch](https://www.adafruit.com/product/2279) Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2279) [Related Guides to the Product](https://learn.adafruit.com/products/2279/guides) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ### 64x32 Flexible RGB LED Matrix - 4mm Pitch [64x32 Flexible RGB LED Matrix - 4mm Pitch](https://www.adafruit.com/product/3826) If you've played with multiplexed RGB matrices, you may have wondered "hey, could we possibly manufacture these on a thin enough PCB, so it's flexible?" and the answer is  **Yes!**  [T](http://www.adafruit.com/?q=64x32%20RGB) No Longer Stocked [Buy Now](https://www.adafruit.com/product/3826) [Related Guides to the Product](https://learn.adafruit.com/products/3826/guides) ## Related Guides - [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md) - [Adafruit MatrixPortal S3](https://learn.adafruit.com/adafruit-matrixportal-s3.md) - [Matrix Portal Creature Eyes](https://learn.adafruit.com/matrix-portal-creature-eyes.md) - [Matrix Portal Money-Sensing Tip Jar](https://learn.adafruit.com/matrix-portal-money-sensing-tip-jar.md) - [Moon Phase Clock for Adafruit Matrix Portal](https://learn.adafruit.com/moon-phase-clock-for-adafruit-matrixportal.md) - [itsaSNAP Daily Weather Forecast Board](https://learn.adafruit.com/itsasnap-daily-weather-forecast-board.md) - [Adafruit RGB Matrix + Real Time Clock HAT for Raspberry Pi](https://learn.adafruit.com/adafruit-rgb-matrix-plus-real-time-clock-hat-for-raspberry-pi.md) - [Creating MatrixPortal Projects with CircuitPython](https://learn.adafruit.com/creating-projects-with-the-circuitpython-matrixportal-library.md) - [Ocean Epoxy Resin Lightbox with RGB LED Matrix Image Scroller](https://learn.adafruit.com/ocean-epoxy-resin-lightbox-with-rgb-led-matrix-image-scroller.md) - [Adafruit Protomatter RGB Matrix Library](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library.md) - [RGB Matrix Automatic YouTube ON AIR Sign](https://learn.adafruit.com/rgb-matrix-automatic-youtube-on-air-sign.md) - [Adafruit RGB Matrix FeatherWings](https://learn.adafruit.com/rgb-matrix-featherwing.md) - [Star Trek LCARS Display](https://learn.adafruit.com/star-trek-lcars-display.md) - [Matrix Portal New Guide Scroller](https://learn.adafruit.com/matrix-portal-new-guide-scroller.md) - [Matrix Portal Flow Visualizer](https://learn.adafruit.com/matrix-portal-flow-visualizer.md) - [Matrix Portal M4 Boxing Interval Timer](https://learn.adafruit.com/matrix-portal-m4-boxing-interval-timer.md) - [Stream Deck controlled RGB Message Panel using Adafruit IO](https://learn.adafruit.com/stream-deck-controlled-rgb-message-panel-using-adafruit-io.md)