Skip to main content
We welcome contributions to the Cricfy Kodi Plugin! Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated.

​
Credits

Major portions of the code were ported from the following repository: https://github.com/NivinCNC/CNCVerse-Cloud-Stream-Extension/tree/master/CricifyProvider Thanks to NivinCNC for their work on the original Cricfy provider extension for Cloudstream. This Kodi plugin is based on their implementation, adapted to work within the Kodi ecosystem.
Please refer to the original Cloudstream extension project for additional context and reference implementations.

​
Development setup

To contribute to the project, you’ll need to set up your development environment.

​
Prerequisites

  • Python 3.8 or higher
  • Kodi installation (for testing)
  • Git for version control
  • Text editor or IDE (VS Code, PyCharm, etc.)

​
Clone the repository

git clone https://github.com/itsyourap/cricfy-kodi-plugin.git
cd cricfy-kodi-plugin

​
Install dependencies

The plugin uses several Python libraries:
  • requests - HTTP requests
  • pycryptodomex - AES encryption/decryption
  • Kodi addon dependencies (xbmc, xbmcgui, xbmcplugin, xbmcaddon, xbmcvfs)
Kodi addon dependencies are only available within the Kodi environment. For local development, you may want to create stub modules for type checking and linting.

​
Testing in Kodi

To test your changes:
  1. Create a symbolic link from your development directory to Kodi’s addon directory:
# Linux/macOS
ln -s /path/to/cricfy-kodi-plugin/plugin.video.cricfy ~/.kodi/addons/plugin.video.cricfy

# Windows (run as Administrator)
mklink /D "%APPDATA%\Kodi\addons\plugin.video.cricfy" "C:\path\to\cricfy-kodi-plugin\plugin.video.cricfy"
  1. Enable debug logging in Kodi (Settings → System → Logging)
  2. Launch the addon and check the Kodi log for errors

​
Code structure guidelines

Follow these guidelines when contributing code to maintain consistency and quality.

​
Module organization

The plugin follows a modular structure:
  • main.py - Entry point and routing logic
  • service.py - Background service for initialization
  • lib/ - Core business logic modules
    • config.py - Configuration and cache setup
    • providers.py - Provider and channel management
    • m3u_parser.py - M3U playlist parsing
    • crypto_utils.py - Encryption/decryption utilities
    • remote_config.py - Firebase Remote Config integration
    • req.py - HTTP request utilities
    • logger.py - Logging utilities
When adding new functionality, consider whether it belongs in an existing module or requires a new module in lib/.

​
Coding style

  • Use snake_case for function and variable names
  • Use PascalCase for class names
  • Add docstrings to functions explaining their purpose
  • Keep functions focused on a single responsibility
  • Use type hints where appropriate (Python 3.8+ syntax)
Example: 
def fetch_channels(provider_url: str, timeout: int = 15) -> list[PlaylistItem]:
  """
  Fetches and parses channels from a provider's M3U playlist.
  
  Args:
    provider_url: URL of the M3U playlist
    timeout: Request timeout in seconds
    
  Returns:
    List of PlaylistItem objects
  """
  content = fetch_url(provider_url, timeout=timeout)
  return parse_m3u(content)

​
Error handling

  • Always handle exceptions gracefully
  • Use the logger module for error reporting
  • Provide user-friendly error messages via Kodi dialogs when appropriate
Example: 
try:
  channels = get_channels(provider_url)
except Exception as e:
  log_error("main", f"Error fetching channels: {e}")
  xbmcgui.Dialog().notification(
    'Error', 'Failed to fetch channels', xbmcgui.NOTIFICATION_ERROR)
  return

​
Caching best practices

  • Use descriptive cache keys
  • Set appropriate TTL values based on data volatility
  • Hash long or variable-length keys using _hash_key()
  • Always validate cached data before using it
Example: 
cache_key = f"data_{_hash_key(url)}"
cached_data = cache.get(cache_key)

if cached_data and isinstance(cached_data, str):
  return json.loads(cached_data)

# Fetch and cache new data
data = fetch_new_data(url)
cache.set(cache_key, json.dumps(data))

​
How to submit pull requests

Follow these steps to submit your contribution:

​
1. Fork and create a branch

Fork the repository on GitHub and create a new branch for your changes: 
git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/add-epg-support
  • fix/channel-parsing-error
  • docs/improve-installation-guide

​
2. Make your changes

  • Write clear, focused commits
  • Follow the code structure guidelines above
  • Test your changes thoroughly in Kodi
  • Update documentation if needed

​
3. Commit your changes

Write clear commit messages: 
git add .
git commit -m "Add EPG support for live channels"
Good commit message examples:
  • “Fix channel parsing when tvg-logo is missing”
  • “Add retry logic for failed provider requests”
  • “Update installation instructions for Matrix”

​
4. Push and create a pull request

Push your branch to your fork: 
git push origin feature/your-feature-name
Then create a pull request on GitHub with:
  • Clear description of what changes you made
  • Explanation of why the changes are needed
  • Any testing you performed
  • Screenshots or logs if applicable

​
5. Respond to feedback

Be responsive to code review comments and make requested changes promptly.
Pull requests should focus on a single feature or fix. If you have multiple unrelated changes, submit separate pull requests.

​
Testing checklist

Before submitting a pull request, verify:
  • Plugin installs successfully in Kodi
  • Providers list loads correctly
  • Channels display for multiple providers
  • Video playback works with at least one stream
  • DRM content plays (if applicable)
  • No errors in Kodi log during normal operation
  • Cache invalidation works as expected
  • Changes don’t break existing functionality

​
Reporting issues

If you find a bug or have a feature request:
  1. Check if the issue already exists on GitHub
  2. Create a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Kodi version and platform
    • Relevant log excerpts (enable debug logging)
    • Screenshots if applicable

​
License

By contributing to this project, you agree that your contributions will be licensed under the GNU General Public License version 3.0 or later. GNU GPLv3 Image You can use, study, share and modify the code at your will. Contributions can be redistributed and/or modified under the terms of the GNU General Public License version 3 or later published by the Free Software Foundation.

​
Repository

The project is hosted on GitHub: https://github.com/itsyourap/cricfy-kodi-plugin

​
Questions?

If you have questions about contributing, feel free to:
  • Open a discussion on GitHub
  • Check existing issues and pull requests for examples
  • Review the source code documentation
Start with small contributions like fixing typos, improving documentation, or addressing “good first issue” tickets to familiarize yourself with the project.
Thank you for contributing to the Cricfy Kodi Plugin!

Build docs developers (and LLMs) love

Get started for freeTalk to us