First of all; if You do not read this file ... don't expect any sort of
response to any of Your emails - that simply ain't going to happen :)

# I'm going to tell You...

a) why it has taken so bloody long to update the software
b) how You should/could use it for something and
c) why You probably should not use it live

Now... hear a bit of history - might be boring, but might explain the
first sentence...

## Traktor Metadata Listener

The software previously known as "Traktor Metadata Listener" was released
to the public on the turn of September/October way back in 2009. Even
though it was presented as a software for tweeting Your currently playing
track(s) to Twitter ... it was actually a technology proof-of-concept for
listening to an audio-stream with metadata (like the stream/track info)
for the company I owned and worked for at the time; Disco-Nova.

The software went from v0.1 to v0.4 (which is probably the version You've
already seen before) in ... about two weeks. What I had at v0.3 worked
nicely for what we needed for the expected "proof-of-concept" at the
time... and it was something other people were interested in, so ... that
version went public. The company had the information it needed; "it is
possible". Then the software went "a bit viral" *quickly* and it was
quickly rewritten to support multiple operating systems. This rewrite was
released to the public as v0.4 ... and for nearly 10 years that has been
the version You've been able to download from Disco-Nova's site.

In the early 2010 I sold the majority of Disco-Nova to another party. I
still remained as a DJ - and as an occasional software developer for the
company when that was needed. I also had other job, so ... Disco-Nova
-stuff was not really too high on my list at this time.

Of course ... the main functionality for which people were *initially*
interested in the software for; sending tweets out to Twitter - broke
completely when Twitter started requiring OAuth -authentication from
third party applications in late 2010. At this time, various alpha-
versions of the software were unofficially released; some with similar
functionality to send data towards last.fm, some that updated specific
named files on the filesystem whenever they "heard" a new track info.
Naturally - none of these versions were never "officially" released. And
never will (because I no longer have any of them).

Soon after this I mentally separated myself from Disco-Nova ... not out
of any sort of spite, but because I was spending my time traveling
through the various corners of the world and spending my time deejaying.
Frankly - maintaining "old POCs" was seriously not high on my priorities
at the time. And pretty much about around this time I expanded the
mental separation into a financial separation; only thing of Disco-Nova
I retained for myself was... the domain-name on the Interwebs... because
it had a bit of sentimental value; I registered it back in 1997 during
"Web 1.0" ... it was getting to its teens; You don't go around throwing
teens under the train :) However, this financial separation also meant
that I no longer held any ownership over the code for Traktor Metadata
Listener.

Then again - while I was not able to use the code for anything in fear
of legal repercussions ... there was absolutely nothing stopping me from
nudging people asking for details into the right direction. And that I
did; as many persons as possible asking details for the protocol did
(eventually) get email from me directing them to any of the official
documentation and (if I felt like it) some friendly hints towards
"why/how the official documentation is incorrect".

Step forwards nearer to this day...

The owner of Disco-Nova's name, intellectual property, etc. went
bankrupt in 2015. Since then, I've been having discussions with (way too
numerous) lawyers and other legal advisors to determine whether there is
any code from "back in the day" I am legally allowed to use. Finally, a
few months ago, I finally received all the "go-aheads" from all the
parties involved that allowed me to actually do something with the
nearly decade old code I still had laying about - as far as I was
actually doing some of the major things differently.

Heh!! Ok - No problem; the way I wrote code (nearly) a decade ago is
nothing like the way I write code these days. So ... no biggie on that
front :) Just need to implement the things a bit differently.

And at this point I need to mention ... at no point were the "then
owners of Disco-Nova" trying to stop me from doing anything - they just
were not interested in it ... they had no use for it, but "if you own
something, letting others use it is like throwing money in the wind".
They were not good with software development ... and even worse in DJ-
services ... but they tried their best ;)

Of course ... Traktor Metadata Listener has been written in Pascal - a
language I have not used in years :D Thus ... it took me a while to get
reacquainted with how the language works ... and a bit longer to figure
out what advances have been made to the language in the past decade.

So... Traktor Metadata Listener (i.e. the "Harvester" from now on) is
back! At least for this version ;)

## Harvester

Unlike before, there is no longer a Linux-version available because the
compatibility issues with a pre-compiled executable file were ... insane.
I think I may have done something wrong there, but ... the Linux-version
just seems to break every few weeks for no apparent reason. It just ain't
worth the hassle (after all - there isn't even a Traktor -version for
Linux, so...)

The package holds native OS X 32-bit/64-bit & native Windows 32-bit
-versions of the software.

### "These are probably not the droids You're looking for!"

The files in this package should be considered "beta"-quality at best.
As my personal opinion;

a) this should not be used in any live situation
b) this should not be used without looking into them

On my own tests - running the "Harvester" on the same machine as Traktor
resulted in serious lag in Traktor 3 (reason being unclear; it really
shouldn't've had). The software should be compatible with any recent
version of Traktor. Personally I've tested it with T2 & T3 (it should
work with T1, because the original code was written for that, and hasn't
really changed much since).

### "These might be the droids You're looking for!"

When You start the software, it will spawn Your default browser with a
quick & dirty visualisation of the incoming tracks. For some users, this
might be exactly what they want... but You're actually supposed to write
Your own "visualizer". The software offers a REST-endpoint to get the
details for the "currently playing track/stream". For details; check
what the default browser visualizer is doing.

You are not limited to using the REST-endpoint through a browser. Just
build Your visualizer in *any* way You wish!

## Setting up Harvester

- Download the software (You've already done that, I believe:)
- Start (from the command line) the version appropriate for Your OS:
  - metadata-osx32 => OS X, 32-bit
  - metadata-osx64 => OS X, 64-bit
  - metadata-win32.exe => Windows
- By default, the server will start in port 8080 ... override this by:
  - running "metadata-xyz42 --port=1234" (replace xyz42 with proper
    version and 1234 with the port You want to use; remember that ports
    1-1024 generally need Administrator/root-privileges)
- If the port is already occupied (or needs more privileges than You
  have), the software will tell You that it is "Unable to bind". If this
  happens, You should try another port.
- Set Your Traktor to broadcast to the address the server is running in,
  on the port it is running in, using password ":" (without quotes; that
  is the "colon"-character); this will only work with this paricular
  version of the software - none of the older ones, none of the future
  ones.
- Play some music!

## Why You should not be using this?

First of all; this is a beta-build. Or rather - not even that ... this
is a beta-debug build. It does not behave in a fashion You'd expect any
normal software to work.

This version has *not* been "pen-tested" for vulnerabilities. Remember
that the software does set up a server that listens for everything that
is coming from the net. If You're running this on a local, insulated
network, You might be relatively safe ... but as a software developer I
would never trust that!

Personally, for best performance, I would suggest running the server on
a separate machine from Your DJ-rig.

# Now, finally...

Alright - You've been warned. You've been told not to use this software.
You're been a trooper and gotten this far. Assuming You've actually read
everything above and You still decide to run this software and there's
something You're wondering; *now* You're allowed to contact me by email
at markku.uttula@disconova.com ... it might take a while for me to get
back to You, but ... eventually - maybe ;)
