{"id":13466353,"url":"https://github.com/Stremio/addon-helloworld","last_synced_at":"2025-03-25T21:32:08.928Z","repository":{"id":3216324,"uuid":"48555053","full_name":"Stremio/addon-helloworld","owner":"Stremio","description":"👋 Hello World add-on for Stremio","archived":false,"fork":false,"pushed_at":"2024-04-01T13:29:32.000Z","size":6190,"stargazers_count":40,"open_issues_count":4,"forks_count":18,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-10-29T19:18:22.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stremio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-24T19:43:37.000Z","updated_at":"2024-09-14T21:10:32.000Z","dependencies_parsed_at":"2024-10-29T19:04:49.549Z","dependency_job_id":null,"html_url":"https://github.com/Stremio/addon-helloworld","commit_stats":{"total_commits":88,"total_committers":5,"mean_commits":17.6,"dds":0.6136363636363636,"last_synced_commit":"d1eafa0e720b2ee8eb4b2a327039559f64bb35bf"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stremio%2Faddon-helloworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stremio%2Faddon-helloworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stremio%2Faddon-helloworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stremio%2Faddon-helloworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stremio","download_url":"https://codeload.github.com/Stremio/addon-helloworld/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245548195,"owners_count":20633533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:00:42.803Z","updated_at":"2025-03-25T21:32:07.612Z","avatar_url":"https://github.com/Stremio.png","language":"JavaScript","funding_links":[],"categories":["Addon Developer Resources","JavaScript"],"sub_categories":["Catalogs"],"readme":"# Hello world add-on for Stremio\n\n### Adds a few public domain movies to Stremio\n\nThis example shows how to make a Stremio Add-on with Stremio's [Add-on SDK](https://github.com/Stremio/stremio-addon-sdk).\n\nAlternatively, you can also see how to make a Stremio Add-on with the [Express](https://www.npmjs.com/package/express) NPM module at [Stremio Express Add-on Hello World](https://github.com/Stremio/addon-helloworld-express), or explore our [many other examples](https://github.com/Stremio/stremio-addon-sdk/tree/master/docs/examples).\n\n\n## Quick Start\n\n```bash\nnpm install\nnpm start\n```\n\nThen run Stremio, click the add-on button (puzzle piece icon) on the top right, and write `http://127.0.0.1:7000/manifest.json` in the \"Addon Url\" field on the top left.\n\n\n## Basic tutorial on how to re-create this add-on step by step\n\nStep 1: init a npm project\n=========================\n\n**Pre-requisites: Node.js, Git**\n\nThis is the first, boilerplate step of creating an add-on for Stremio. Create a node.js project and add the [stremio-addons](http://github.com/Stremio/stremio-addons) module as dependency.\n\n```bash\nmkdir stremio-hello-world\ncd stremio-hello-world\nnpm init\nnpm install --save stremio-addon-sdk@1.0.x\ngit add *\ngit commit -a -m \"initial commit\"\n```\n\n**NOTE:** to test this add-on, you need to complete Step 6. Start the add-on with `node server.js` and add the add-on to stremio by going to the *Addons* page (top right icon) and typing `http://127.0.0.1:7000/manifest.json` in the text field in the top left and pressing enter.\n\nStep 2: Create addon.js, fill manifest\n===========================\n\nIn this step, we define the add-on name, description and purpose.\n\nCreate an `addon.js` file:\n```javascript\nconst { addonBuilder } = require(\"stremio-addon-sdk\");\n\nconst manifest = {\n    \"id\": \"org.stremio.helloworld\",\n    \"version\": \"1.0.0\",\n\n    \"name\": \"Hello World Addon\",\n    \"description\": \"Sample addon providing a few public domain movies\",\n\n    //\"icon\": \"URL to 256x256 monochrome png icon\", \n    //\"background\": \"URL to 1024x786 png/jpg background\",\n\n    // set what type of resources we will return\n    \"resources\": [\n        \"catalog\",\n        \"stream\"\n    ],\n\n    \"types\": [\"movie\", \"series\"], // your add-on will be preferred for these content types\n\n    // set catalogs, we'll have 2 catalogs in this case, 1 for movies and 1 for series\n    \"catalogs\": [\n        {\n            type: 'movie',\n            id: 'helloworldmovies'\n        },\n        {\n            type: 'series',\n            id: 'helloworldseries'\n        }\n    ],\n\n    // prefix of item IDs (ie: \"tt0032138\")\n    \"idPrefixes\": [ \"tt\" ]\n\n};\n```\n\nStep 3: init an add-on server\n============================\n\nAdd to your addon.js:\n```javascript\nconst builder = new addonBuilder(manifest);\n```\n\nStep 4: basic streaming\n==============================\n\nTo implement basic streaming, we will set-up a dummy dataset with a few public domain movies. \n\n```javascript\nconst dataset = {\n    // Some examples of streams we can serve back to Stremio ; see https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/stream.md\n    \"tt0051744\": { name: \"House on Haunted Hill\", type: \"movie\", infoHash: \"9f86563ce2ed86bbfedd5d3e9f4e55aedd660960\" }, // torrent\n    \"tt1254207\": { name: \"Big Buck Bunny\", type: \"movie\", url: \"http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4\" }, // HTTP stream\n    \"tt0031051\": { name: \"The Arizone Kid\", type: \"movie\", ytId: \"m3BKVSpP80s\" }, // YouTube stream\n    \"tt0137523\": { name: \"Fight Club\", type: \"movie\", externalUrl: \"https://www.netflix.com/watch/26004747\" }, // redirects to Netflix\n    \"tt1748166:1:1\": { name: \"Pioneer One\", type: \"series\", infoHash: \"07a9de9750158471c3302e4e95edb1107f980fa6\" }, // torrent for season 1, episode 1\n};\n```\n\nAnd then implement ``defineStreamHandler`` as follows:\n\n```javascript\n// Streams handler\nbuilder.defineStreamHandler(function(args) {\n    if (dataset[args.id]) {\n        return Promise.resolve({ streams: [dataset[args.id]] });\n    } else {\n        return Promise.resolve({ streams: [] });\n    }\n})\n```\n\n**As you can see, this is an add-on that allows Stremio to stream 4 public domain movies and 1 series episode - in very few lines of code.**\n\nDepending on your source, you can implement streaming (`defineStreamHandler`) or catalogs (`defineCatalogHandler`) of ``movie``, ``series``, ``channel`` or ``tv`` content types.\n\nTo load that add-on in the desktop Stremio, click the add-on button (puzzle piece icon) on the top right, and write `http://127.0.0.1:7000/manifest.json` in the \"Addon Repository Url\" field on the top left.\n\nStep 5: implement catalog\n==============================\n\nWe have 2 methods serving meta: \n\n- ``defineCatalogHandler`` serves basic metadata (id, type, name, poster) and handles loading of both the catalog feed and searching;\n\n- ``defineMetaHandler`` serves [advanced metadata](https://github.com/Stremio/stremio-addon-sdk/blob/docs/docs/api/responses/meta.md) for individual items, for imdb ids though (what we're using in this example add-on), we do not need to handle this method at all as it is handled automatically by Stremio's Cinemeta\n\n**For now, we have the simple goal of loading the movies we provide on the top of Discover.**\n\nAppend to addon.js:\n\n```javascript\nconst METAHUB_URL = \"https://images.metahub.space\"\n\nconst generateMetaPreview = function(value, key) {\n    // To provide basic meta for our movies for the catalog\n    // we'll fetch the poster from Stremio's MetaHub\n    // see https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/api/responses/meta.md#meta-preview-object\n    const imdbId = key.split(\":\")[0]\n    return {\n        id: imdbId,\n        type: value.type,\n        name: value.name,\n        poster: METAHUB_URL+\"/poster/medium/\"+imdbId+\"/img\",\n    }\n}\n\nbuilder.defineCatalogHandler(function(args, cb) {\n    // filter the dataset object and only take the requested type\n    const metas = Object.entries(dataset)\n        .filter(([_, value]) =\u003e value.type === args.type)\n        .map(([key, value]) =\u003e generateMetaPreview(value, key))\n\n    return Promise.resolve({ metas: metas })\n})\n```\n\nStep 6: putting everything together\n===================\n\nIt's time to run our add-on!\n\nAppend to addon.js:\n```javascript\nmodule.exports = builder.getInterface()\n```\n\nAnd now create a new file, server.js, that only contains:\n\n```javascript\nconst { serveHTTP } = require(\"stremio-addon-sdk\");\n\nconst addonInterface = require(\"./addon\");\nserveHTTP(addonInterface, { port: 7000 });\n```\n\nRun the add-on with `npm start` and add `http://127.0.0.1:7000/manifest.json` as the Repository URL in Stremio.\n\nThis add-on also supports serverless deployment, just create a new file called serverless.js, that contains:\n\n```javascript\nconst { getRouter } = require(\"stremio-addon-sdk\");\nconst addonInterface = require(\"./addon\");\n\nconst router = getRouter(addonInterface);\n\nmodule.exports = function(req, res) {\n    router(req, res, function() {\n        res.statusCode = 404;\n        res.end();\n    });\n}\n```\n\nYou can check out [this now.json file](./now.json) that would make this add-on work with now.sh serverless deployment.\n\nNow, if you want to deploy your add-on and make it accessible publically, proceed to [our deployment guide](https://github.com/Stremio/stremio-addon-sdk/blob/master/docs/deploying/deploying.md).\n\n\nStep 7: result\n===================\n\n![addlink](https://user-images.githubusercontent.com/1777923/43146711-65a33ccc-8f6a-11e8-978e-4c69640e63e3.png)\n![discover](screenshots/stremio-addons-discover.png)\n![board](screenshots/stremio-addons-board.png)\n![streaming from add-on](screenshots/streaming.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStremio%2Faddon-helloworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStremio%2Faddon-helloworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStremio%2Faddon-helloworld/lists"}