Merge pull request #249 from Stremio/subtitle-details

Document Stream Behavior Hints For Subtitles

docs/api/responses/stream.md

@@ -24,4 +24,7 @@ Used as a response for [`defineStreamHandler`](../requests/defineStreamHandler.m
     - `countryWhitelist`: which hints it's restricted to particular countries  - array of ISO 3166-1 alpha-3 country codes **in lowercase** in which the stream is accessible
     - `notWebReady`: applies if the protocol of the url is http(s); needs to be set to `true` if the URL does not support https or is not an MP4 file
     - `bingeGroup`: if defined, addons with the same `behaviorHints.bingeGroup` will be chosen automatically for binge watching; this should be something that identifies the stream's nature within your addon: for example, if your addon is called "gobsAddon", and the stream is 720p, the bingeGroup should be "gobsAddon-720p"; if the next episode has a stream with the same `bingeGroup`, stremio should select that stream implicitly
-    - `proxyHeaders`: Only applies to `url`s; **When using this property, you must also set `stream.behaviorHints.notWebReady: true`**; This is an object containing `request` and `response` which include the headers that should be used for the stream (example value: `{ "request": { "User-Agent": "Stremio" } }`)
+    - `proxyHeaders`: only applies to `url`s; **When using this property, you must also set `stream.behaviorHints.notWebReady: true`**; This is an object containing `request` and `response` which include the headers that should be used for the stream (example value: `{ "request": { "User-Agent": "Stremio" } }`)
+    - `videoHash`: - string, the calculated [OpenSubtitles hash](http://trac.opensubtitles.org/projects/opensubtitles/wiki/HashSourceCodes) of the video, this will be used when the streaming server is not connected (so the hash cannot be calculated locally), this value is passed to subtitle addons to identify correct subtitles
+    - `videoSize`: - number, size of the video file in bytes, this value is passed to the subtitle addons to identify correct subtitles
+    - `filename`: - string, filename of the video file, although optional, it is highly recommended to set it when using `stream.url` (when possible) in order to identify correct subtitles (addon sdk will show a warning if it is not set in this case), this value is passed to the subtitle addons to identify correct subtitles

src/getRouter.js

@@ -2,6 +2,8 @@ const Router = require('router')
 const qs = require('querystring')
 const cors = require('cors')
 
+const warned = {}
+
 function getRouter({ manifest , get }) {
 	const router = new Router()
 
@@ -89,6 +91,12 @@ function getRouter({ manifest , get }) {
 
 				res.setHeader('Content-Type', 'application/json; charset=utf-8')
 
+				if (!warned.filename && resource === 'stream' && ((resp || {}).streams || []).length)
+					if (resp.streams.find(stream => stream && stream.url && !(stream.behaviorHints || {}).filename)) {
+						warned.filename = true
+						console.warn('streams include stream.url but do not include stream.behaviorHints.filename, this is not recommended, subtitles may not be retrieved for these streams')
+					}
+
 				res.end(JSON.stringify(resp))
 			})
 			.catch(err => {