I have a TiVoHD, and so have written my program specifically to support the features of the TiVoSeries3 and TiVoHD. The newer TiVoPremier units support more codecs and faster transfer speeds, and the earlier Series2 units do not support the 720p or 1080i resolutions that I allow to be transferred to the TiVo. My initial TiVo server serves files from specific shares on the server, \\server\TiVo\* and \\server\Videos\*, which are specified in the registry key and does not have a user interface to modify them. I recursively parse the shares for files FFMPEG reports as video files and present them as a flattened container sorted by date.
[HKEY_LOCAL_MACHINE\SOFTWARE\WimsWorld\WimTiVoServer]
"Container"="//server/TiVo/*;//server/Videos/*"
The TiVo Server operates using the HTTP protocol. It can also operate using SSL/HTTPS. The TiVo itself uses HTTPS for all of the XML transfers, but transfers its videos using HTTP. The videos the TiVo transfers are encrypted using the Media Access Key (MAK) specific to each TiVo. Videos transferred to the TiVo do not need to be encrypted.
There are multiple ways that your server can announce itself to the TiVo. I’m using the simplest to develop, which is broadcasting a specially formatted UDP packet every minute on the local network to port number 2190. An example packet looks like:
tivoconnect=1
method=broadcast
platform=pc/win-nt
machine=FREDS-PC
identity={D936E980-79E3-11D6-A84A-00045A43EEE7}
services=FooService:1234,BarService:4321
Here is a current broadcast from my server indicating that it will serve TiVo compatible media via the HTTP protocol on port 56667. My program follows the tivo recommendation of using a TCP port supplied by the OS, and attempting to use the same port on subsequent restarts of the server. It also generates the GUID and attempts to save and reuse it.
tivoconnect=1
method=broadcast
platform=pc/WinNT:6.2.9200
machine=Acid
identity={FF121976-2D7B-4682-A1DA-464510DCACEB}
services=TiVoMediaServer:56667/http
swversion=20130604103659
After the TiVo has received a broadcast with the service it is interested in, it will make a request of the server to get the top level containers. http://{machine}/TiVoConnect?Command=QueryContainer&Container=/ The server responds with the XML describing the top level containers.
Here’s an example of the code produced by my server, which is named Acid and has a single top level container with the same name. URLs embedded in the XML can be either relative or absolute. I’ve chosen to always use relative URLs because that way I don’t have to embed the TCP port I’m serving data from in the XML.
<?xml version="1.0" encoding="UTF-8"?>
<TiVoContainer xmlns="http://www.tivo.com/developer/calypso-protocol-1.6/">
<Details>
<Title>Acid</Title>
<ContentType>x-tivo-container/tivo-server</ContentType>
<SourceFormat>x-tivo-container/folder</SourceFormat>
<TotalItems>1</TotalItems>
</Details>
<Item>
<Details>
<Title>Acid</Title>
<ContentType>x-tivo-container/tivo-videos</ContentType>
<SourceFormat>x-tivo-container/folder</SourceFormat>
</Details>
<Links>
<Content>
<Url>/TiVoConnect?Command=QueryContainer&Container=%2FTiVoNowPlaying</Url>
<ContentType>x-tivo-container/tivo-videos</ContentType>
</Content>
</Links>
</Item>
<ItemStart>0</ItemStart>
<ItemCount>1</ItemCount>
</TiVoContainer>
When a user goes to the Now Playing screen on the TiVo, the top level containers should show up in the list at the bottom. Selecting the container will cause the TiVo to request the particular container from the server via its content URL. http://{machine}/TiVoConnect?Command=QueryContainer&Container=/Foo
That container may contain TiVoItems which have URLS for both details and content. The TiVo will only request the content URL after it’s successfully requested the URL for the details, which was something that it took a while for me to understand.
Here is an example of the output when the TiVo requests the container with the URL http://acid:56667/TiVoConnect?Command=QueryContainer&Container=/TiVoNowPlaying&ItemCount=1 :
<?xml version="1.0" encoding="UTF-8"?>
<TiVoContainer xmlns="http://www.tivo.com/developer/calypso-protocol-1.6/">
<ItemStart>0</ItemStart>
<ItemCount>1</ItemCount>
<Details>
<Title>Acid</Title>
<ContentType>x-tivo-container/folder</ContentType>
<SourceFormat>x-tivo-container/folder</SourceFormat>
<TotalItems>2116</TotalItems>
</Details>
<Item>
<Details>
<Title>ShowTitle</Title>
<ContentType>video/x-tivo-mpeg</ContentType>
<SourceFormat>video/h264</SourceFormat>
<SourceSize>1805804000</SourceSize>
<Duration>1289860</Duration>
<CaptureDate>0x51b0ff42</CaptureDate>
</Details>
<Links>
<Content>
<ContentType>video/x-tivo-mpeg</ContentType>
<Url>/TiVoConnect/TivoNowPlaying///Acid/TiVo/ShowTitle.mp4</Url>
</Content>
<CustomIcon>
<ContentType>image/*</ContentType>
<AcceptsParams>No</AcceptsParams>
<Url>urn:tivo:image:save-until-i-delete-recording</Url>
</CustomIcon>
<TiVoVideoDetails>
<ContentType>text/xml</ContentType>
<AcceptsParams>No</AcceptsParams>
<Url>/TiVoConnect?Command=TVBusQuery&Url=/TiVoConnect/TivoNowPlaying///Acid/TiVo/ShowTitle.mp4</Url>
</TiVoVideoDetails>
</Links>
</Item>
</TiVoContainer>
When I select “ShowTitle” in the tivo onscreen interface, it will request this same URL, with the anchoritem set to the content URL. It will then display the details about the show on the TV screen. After I select that I want the show to be transferred it first requests an undocumented URL, my server responds that the URL was not found, then the TiVo requests the TiVoVideoDetails URL, and I respond with an XML chunk that I couldn’t find documentation for anywhere and had to fake together from looking at the output of TiVoDecode and pyTiVo. The really ugly bit of the XML is in the initial element declaration. I wasn’t able to make the XML be accepted by the TiVo if it didn’t have the full namespace declarations, even though the hosts listed are not accessable.
<?xml version="1.0" encoding="UTF-8"?>
<TvBusMarshalledStruct:TvBusEnvelope xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xmlns:TvBusMarshalledStruct="http://tivo.com/developer/xml/idl/TvBusMarshalledStruct" xmlns:TvPgdRecording="http://tivo.com/developer/xml/idl/TvPgdRecording" xmlns:TvBusDuration="http://tivo.com/developer/xml/idl/TvBusDuration" xmlns:TvPgdShowing="http://tivo.com/developer/xml/idl/TvPgdShowing" xmlns:TvDbShowingBit="http://tivo.com/developer/xml/idl/TvDbShowingBit" xmlns:TvBusDateTime="http://tivo.com/developer/xml/idl/TvBusDateTime" xmlns:TvPgdProgram="http://tivo.com/developer/xml/idl/TvPgdProgram" xmlns:TvDbColorCode="http://tivo.com/developer/xml/idl/TvDbColorCode" xmlns:TvPgdSeries="http://tivo.com/developer/xml/idl/TvPgdSeries" xmlns:TvDbShowType="http://tivo.com/developer/xml/idl/TvDbShowType" xmlns:TvPgdBookmark="http://tivo.com/developer/xml/idl/TvPgdBookmark" xmlns:TvPgdChannel="http://tivo.com/developer/xml/idl/TvPgdChannel" xmlns:TvDbBitstreamFormat="http://tivo.com/developer/xml/idl/TvDbBitstreamFormat" xs:schemaLocation="http://tivo.com/developer/xml/idl/TvBusMarshalledStruct TvBusMarshalledStruct.xsd http://tivo.com/developer/xml/idl/TvPgdRecording TvPgdRecording.xsd http://tivo.com/developer/xml/idl/TvBusDuration TvBusDuration.xsd http://tivo.com/developer/xml/idl/TvPgdShowing TvPgdShowing.xsd http://tivo.com/developer/xml/idl/TvDbShowingBit TvDbShowingBit.xsd http://tivo.com/developer/xml/idl/TvBusDateTime TvBusDateTime.xsd http://tivo.com/developer/xml/idl/TvPgdProgram TvPgdProgram.xsd http://tivo.com/developer/xml/idl/TvDbColorCode TvDbColorCode.xsd http://tivo.com/developer/xml/idl/TvPgdSeries TvPgdSeries.xsd http://tivo.com/developer/xml/idl/TvDbShowType TvDbShowType.xsd http://tivo.com/developer/xml/idl/TvPgdBookmark TvPgdBookmark.xsd http://tivo.com/developer/xml/idl/TvPgdChannel TvPgdChannel.xsd http://tivo.com/developer/xml/idl/TvDbBitstreamFormat TvDbBitstreamFormat.xsd" xs:type="TvPgdRecording:TvPgdRecording">
<recordedDuration>PT21M29S</recordedDuration>
<vActualShowing />
<vBookmark />
<recordingQuality value="75">HIGH</recordingQuality>
<showing>
<showingBits value="0" />
<time>2013-06-06:21:29:38Z</time>
<duration>PT21M29S</duration>
<program>
<vActor />
<vAdvisory />
<vChoreographer />
<colorCode value="4">COLOR</colorCode>
<description></description>
<vDirector />
<episodeTitle></episodeTitle>
<vExecProducer />
<vProgramGenre />
<vGuestStar />
<vHost />
<isEpisode>false</isEpisode>
<originalAirDate>2013-06-06:21:29:38Z</originalAirDate>
<vProducer />
<series>
<isEpisodic>false</isEpisodic>
<vSeriesGenre />
<seriesTitle>ShowTitle</seriesTitle>
</series>
<showType value="5">SERIES</showType>
<title>ShowTitle</title>
<vWriter />
</program>
<channel>
<displayMajorNumber />
<displayMinorNumber />
<callsign />
</channel>
</showing>
<startTime>2013-06-06:21:29:38Z</startTime>
<stopTime>2013-06-06:21:51:07Z</stopTime>
</TvBusMarshalledStruct:TvBusEnvelope>
After the TvBusMarshalledStruct XML has been transferred to the TiVo the tivo will finally request the content url from the original container listing. When the content is sent, it should be sent using HTTP Chunked Encoding.
My current ffmpeg command line is fairly simple, and mostly copied from my reading of the pyTiVo source code. I make a couple of simple decisions based on the source file codecs. If the video is mpeg2video or the audio is ac3 I use the “-vcodec copy” or “-acodec copy” command,
otherwise I specify those as codecs. I also include the options “-b:v 16384k -maxrate 30000k -bufsize 4096k -ab 448k -ar 48000 -f vob” which I need to spend more time learning about.
One of the gotchas that I spent a significant amount of time debugging was that the SourceSize element in the Item listing is significant. It appears that the tivo pre-allocates space for the file as it starts the transfer and if the transfer is proceeding significantly larger than the reported source size the tivo will close its end of the http connection. I have not verified importance in any internal part of the TvBusMarshalledStruct. I got it working, and have been adding support from metadata as available but that’s it currently.
It’s interesting to me that the transfer speed seems completely governed by the speed of the TiVo processor and what the TiVo is doing. The maximum speed I’ve been able to transfer a file to the TiVo is about 16Mb/s. That speed was achieved while the TiVo was not recording any shows and had a 480p program displayed on the screen in a paused state. If I’m playing a 1080i or 720p program the transfer rate is usually much closer to 7Mb/s. This means that if I’m transferring a program that was recorded in HD on my windows media center from my HDHomeRunPrime, I generally cannot watch in real time because it transfers slightly slower than the data rate of the video and audio.
WimsWorld 