Kermit the Frog Screen Lock Experience

This project brings the iconic Kermit the Frog to your screen with a fullscreen animated GIF and looping MP3 audio. It's a fun little application that demonstrates how to combine multimedia elements using Python.

Preview

Here's a glimpse of what you'll see (make sure you're viewing this on GitHub to see the animation):

Badges

Quick Setup and Running and Setup of the Script - See more info below:

A: Firstly, Install the dependencies in the requirements.txt file.

pip install -r requirements.txt

B: Now all you do is run the Kermit script!

python kermit.py

Command-Line Options (v3.1.0+)

python kermit.py --help                    # Show all options
python kermit.py --gif custom.gif          # Use custom GIF
python kermit.py --audio music.mp3         # Use custom audio
python kermit.py --volume 0.5              # Set initial volume (50%)
python kermit.py --no-sound                # Silent mode (no audio)
python kermit.py --version                 # Show version

Combine options:

python kermit.py --gif cat.gif --audio meow.mp3 --volume 0.3
python kermit.py --gif custom.gif --no-sound

Time @ Work!

Controls

Exit (Secret Password)

• The application will launch in fullscreen mode, displaying the animated GIF and playing the sound.
• Press any key to see the "What's the Secret?" message for 3 seconds.
• To exit:
  • macOS: (Control) ⌃ + (Option) ⌥ + Left Shift
  • Linux: Ctrl + Alt + Left Shift
  • MacBook keyboard: Control + Option + Left Shift (same keys on both platforms!)

Pause/Resume

• To pause/unpause:
  • macOS: (Control) ⌃ + (Option) ⌥ + P
  • Linux: Ctrl + Alt + P
  • MacBook keyboard: Control + Option + P (same keys on both platforms!)

Volume

• Up Arrow - Increase volume
• Down Arrow - Decrease volume

Help

• Run python kermit.py --help to see platform-specific controls

Audio

You can listen to the Kermit the Frog sound here: kermit.mp3

Listen on External Host

Github Commits

Features

• Cross-Platform Support: Works on macOS and Linux (Kali/Debian/Ubuntu) with automatic platform detection and appropriate key bindings.

• Fullscreen Animated GIF Display: Showcases a fullscreen, looping, animated GIF of Kermit the Frog (as you can see above!). The image is automatically scaled to fit your screen while maintaining its original aspect ratio.

• Looping MP3 Audio: Plays a Kermit the Frog MP3 sound file in a continuous loop.

• Secret Exit Combination: Provides a hidden way to exit the application by pressing a platform-specific key combination (see Controls section).

• Pause/Resume: Pause and resume both audio and animation with a key combination.

• Volume Control: Adjust volume with Up/Down arrow keys.

• Interactive Message: Displays a "What's the Secret?" message for 3 seconds when any key (other than the secret exit combination) is pressed.

• Hidden Mouse Cursor: Hides the mouse cursor while the application is running in fullscreen mode.

• Command-Line Help: Run with --help to see platform-specific controls and requirements.

• Custom Media Files: Use --gif and --audio flags to specify custom GIF and audio files.

• Initial Volume Control: Set starting volume with --volume 0.0-1.0 flag.

• Silent Mode: Run without audio using --no-sound flag.

• Graceful Error Handling: Clear error messages when files are missing, with helpful suggestions.

Requirements

• Python 3.7+: This project is written in Python 3. Make sure you have Python 3.7 or higher installed on your system. You can check your Python version by running python --version or python3 --version in your terminal.

• Python Libraries:

  • pygame: Used for audio playback.
  • Pillow (PIL): Used for image processing and handling the animated GIF.
  • tkinter: Used for creating the fullscreen window and handling user input.

• System Packages (Linux):

  • python3-tk: Required for tkinter GUI (sudo apt install python3-tk)
  • Optional: mpg123, libsdl2-mixer for better audio support

My Other Cool Scripts.

Installation

1. Clone the Repository:

   git clone <repository_url>
   cd <repository_directory>

   (Replace <repository_url> with the actual URL of your GitHub repository and <repository_directory> with the name of the directory.)

2. Install System Dependencies:

   macOS:

   # tkinter is included with Python from python.org or Homebrew
   # If missing:
   brew install [email protected]

   Linux (Kali/Debian/Ubuntu):

   sudo apt update
   sudo apt install python3-tk

3. Install Python Dependencies:

   pip install -r requirements.txt

   Or manually:

   pip install pygame Pillow

Socials

Usage

1. Place Files: Ensure that the following files are in the same directory as the kermit.py script:

   • kermit.mp3: The Kermit the Frog audio file.
   • kermit.gif: The animated GIF of Kermit the Frog (the one displayed above!).

2. Run the Script:

   A: Firstly, Install the dependencies in the requirements.txt file.

   pip install -r requirements.txt

   B: Now all you do is fun the Kermit script!

   python kermit.py

3. Interaction:

   • The application will launch in fullscreen mode, displaying the animated GIF and playing the sound.
   • Press any key to see the "What's the Secret?" message for 3 seconds.
   • To exit: See Controls section above for platform-specific keys
   • The script auto-detects your OS and shows the correct key bindings on startup.

Code Structure

The kermit.py script is organized into the KermitApp class, which handles the various functionalities:

• __init__(): Initializes the application, loads the image and sound, creates the window, and sets up event bindings.
• bind_keys(): Binds key press and release events to their respective handler functions.
• on_key_press(), on_key_release(), on_any_key_press(): Handle key press and release events, including checking for the secret exit combination and triggering the message display.
• check_secret_combination(): Checks if the secret key combination is pressed.
• play_sound_loop(): Plays the sound file in a loop (runs in a separate thread).
• update_image(): Updates the displayed GIF frame to create the animation (called repeatedly using tkinter's after() method).
• update_message(): Manages the display and hiding of the "What's the Secret?" message.
• start(): Starts the sound thread, the image animation, message updates, and the tkinter main loop.
• stop(): Stops the sound, destroys the window, and terminates the application.

Troubleshooting

• MP3 Playback Issues: If you encounter problems with MP3 playback, you might need to install the mpg123 library, which can sometimes improve Pygame's MP3 support. Installation instructions for mpg123 vary by operating system (e.g., brew install mpg123 on macOS with Homebrew, sudo apt-get install mpg123 on Ubuntu/Debian).
• File Not Found: Double-check that kermit.mp3 and kermit.gif are in the files/ subdirectory relative to the kermit.py script.
• tkinter Not Found (Linux): Install with sudo apt install python3-tk
• Key Combinations Not Working (Linux VM): If running Linux in a VM on macOS, use the Option key (⌥) on your MacBook keyboard - it maps to Alt in Linux.
• Platform Not Detected: Run python kermit.py --help to see which platform was detected and the correct key bindings.

Contributing

Feel free to fork this repository and submit pull requests with enhancements or bug fixes.

License

This project is licensed under the MIT License - see the LICENSE file for details.